Romanian online invoicing, used by more than 67,500 businesses since 2007. Work on your own factureaza.ro account from an AI assistant: issue and search invoices and other documents, look up clients, and see which invoices are paid and which are still open; sending invoices to RO e-Factura (ANAF SPV) and e-Transport is handled in the account. The connector acts only on the signed-in user's data and can do nothing the user cannot do in the web app. Connect with your account's API key as a Bearer
Scored across 63 tools
Tools mostly map to a single resource plus action, and the descriptions clarify generic tools like get_document_pdf, count_records, and get_supplier_document. There is some mild overlap between search_invoices, invoices_summary, and report_* tools, but their boundaries are generally clear.
The set uses a mostly consistent snake_case verb_noun convention such as create_client, search_invoices, delete_payment, and update_product. A few exceptions like invoices_summary, export_efactura_xml, and get_document_pdf are readable but slightly deviate from the dominant pattern.
With 63 tools, the surface is far above a well-scoped MCP set and forces agents to navigate many parallel CRUD/search variants across document types. The broad invoicing domain explains some breadth, but consolidation would noticeably improve usability.
Core entities like clients, products, invoices, payments, and suppliers have CRUD coverage, and the reporting plus e-Factura features are strong. However, several document types support create/search/delete but not update, and stock/notice operations are only partially exposed, leaving notable lifecycle gaps.
Return the exact total count of records for a given model type in the account. Use this to answer "how many X do I have?" questions. Valid models: clients, products, invoices, proforma_invoices, receipts, orders, notices, payments, suppliers, supplier_invoices, supplier_orders, supplier_proforma_invoices, supplier_fiscal_receipts, simplified_supplier_invoices, stock_warehouses, stock_documents, stock_movements.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | Model to count. One of: clients, products, invoices, proforma_invoices, receipts, orders, notices, payments, suppliers, supplier_invoices, supplier_orders, supplier_proforma_invoices, supplier_fiscal_receipts, simplified_supplier_invoices, stock_warehouses, stock_documents, stock_movements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the behavioral burden. It does usefully disclose that the result is an exact total for the whole account (no filtering), but says nothing about permissions, whether archived/deleted records are included, or performance/cost of counting large models.
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 opening purpose and the usage sentence are front-loaded and earn their place. However, the 17-value model list is duplicated verbatim from a schema that already covers it at 100%, roughly tripling the length for zero added 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 one-parameter, non-destructive read with no output schema, purpose, trigger, and scope are all covered. Only edge cases (does the count include soft-deleted or draft documents) are left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `model` parameter is fully documented in-schema. The description's enumeration of valid models adds no meaning beyond the schema text, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the exact total count of records') scoped to a model type within the account. The 'exact total' framing implicitly separates it from the numerous search_*/list_* siblings, though none are named explicitly.
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?
'Use this to answer "how many X do I have?" questions' gives a concrete trigger condition. It stops short of naming an alternative (e.g. use search_invoices when you also need the rows) or stating exclusions, so it's clear context rather than a full routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new client in the account.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | No | Fiscal code / CUI / VAT number (optional) | |
| city | Yes | City | |
| name | Yes | Client full name or company name | |
| No | Email address (optional) | ||
| address | Yes | Street address | |
| country | Yes | Country code, e.g. "RO", "DE" | |
| telephone | No | Phone number (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it discloses almost nothing. It implies a write but says nothing about duplicate handling, idempotency, required-field validation errors, permissions, or what the returned identifier looks like. 'in the account' is the only extra context.
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 with no padding, so nothing is wasted. However, the extreme brevity looks like under-specification rather than disciplined concision for a 7-parameter mutation.
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 create/mutation tool with zero annotations and no output schema, the description should address duplicates, failures, and return behavior. None of that is present, leaving an agent under-informed before a write.
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 all seven parameters including required-vs-optional are already documented. The description adds no parameter meaning beyond the schema, which is the expected baseline here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new client'), which is unambiguous about the operation. It does not distinguish itself from siblings like create_supplier, so an agent must infer the client-vs-supplier boundary from the names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance: nothing about checking for an existing client first (search_clients), when to prefer create_supplier, or what prerequisites exist. The sentence simply restates the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new invoice for a client with one or more line items.
| Name | Required | Description | Default |
|---|---|---|---|
| series | No | Invoice series name (uses account default if omitted; if creation fails because the default series belongs to another year, call list_series and pass a name matching the document year) | |
| currency | Yes | Currency code, e.g. "RON", "EUR", "USD" | |
| due_days | No | Days until payment is due | |
| client_id | No | Client ID (from search_clients) | |
| client_city | No | Client city (if client_id not provided) | |
| client_name | No | Client name (if client_id not known) | |
| document_date | No | Invoice date in YYYY-MM-DD format (defaults to today) | |
| exchange_rate | No | Exchange rate to domestic currency (required when currency is not RON) | |
| client_address | No | Client address (if client_id not provided) | |
| client_country | No | Client country code (if client_id not provided) | |
| lower_annotation | No | Text below line items | |
| upper_annotation | No | Text above line items | |
| document_positions | Yes | Line items on the invoice | |
| document_series_counter | No | Invoice number within the series (auto-incremented if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden for a mutation tool, yet it says nothing about permissions, whether the invoice is a draft or immediately final, numbering/auto-increment effects, e-Factura implications, or reversibility. 'Create' implies a write, but the significant consequences of that write are left entirely undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence with zero waste and the action front-loaded. It is efficient, though its brevity borders on under-specification rather than exemplary conciseness.
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 14-parameter mutation tool with nested line items, no annotations, and no output schema, a single sentence is not enough — the agent gets no information about return value (ID? number?), side effects, or error handling. The rich schema covers inputs but the descriptive layer is nearly empty for a consequential write 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?
Schema description coverage is 100%, so the schema already documents all 14 parameters in depth (currency, due_days, series fallback, per-line discount gating). The description adds no parameter meaning beyond naming 'line items', so the baseline 3 is appropriate given the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new invoice') plus scope ('for a client with one or more line items'), so the agent knows exactly what is produced. It does not distinguish this tool from close siblings like create_proforma_invoice, create_simplified_supplier_invoice, or create_supplier_invoice, leaving the agent to infer from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this instead of create_proforma_invoice, create_simplified_supplier_invoice, or create_order, nor any prerequisites (client setup, series availability). Apart from the schema hinting at series fallback via list_series, the description offers nothing on selection or sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new order (comandă) for a client.
| Name | Required | Description | Default |
|---|---|---|---|
| series | No | Order series name (uses account default if omitted; provide it when the default series has a wrong year or a clashing number) | |
| currency | Yes | Currency code, e.g. "RON" | |
| client_id | No | Client ID | |
| client_city | No | Client city | |
| client_name | No | Client name | |
| document_date | No | Date in YYYY-MM-DD format (defaults to today) | |
| client_address | No | Client address | |
| client_country | No | Client country code | |
| document_positions | Yes | Line items | |
| document_series_counter | No | Number within the series (auto-incremented if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, but it only restates the operation. It does not explain numbering/series behavior, side effects, validation gates, required permissions, or what happens when optional client fields are omitted.
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 single sentence is concise and front-loaded, but it is under-specified for a ten-parameter creation tool with no annotations. Brevity here reflects missing information rather than efficient communication.
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 tool is complex: ten parameters, mutation semantics, no annotations, and no output schema. The schema is rich, but the description does not cover usage context, side effects, or important interactions such as series defaults and discount gating.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all ten parameters, including the nuanced discount_rate behavior. The description adds no parameter meaning beyond what the schema provides, making 3 the appropriate baseline.
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 order for a client. It is clearer than a bare name but does not explicitly distinguish this client order from sibling tools such as create_supplier_order, create_invoice, or create_proforma_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?
There is no guidance on when to use create_order instead of create_invoice, create_proforma_invoice, or create_supplier_order, nor any prerequisites or exclusions. The agent must infer usage entirely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a payment linked to an invoice, proforma invoice, order, or supplier invoice. Exactly one of invoice_id, proforma_invoice_id, order_id, or supplier_invoice_id must be supplied. Provide the amount to record; to pay a document in full, read its outstanding balance first (e.g. get_invoice) and pass that value.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Payment amount to record (required). To settle a document in full, fetch its outstanding balance first and pass it here. | |
| currency | No | Currency code, e.g. "RON", "EUR"; defaults to the document currency when omitted | |
| order_id | No | Order ID to link the payment to | |
| invoice_id | No | Invoice ID to link the payment to | |
| description | No | Notes / description | |
| payment_date | Yes | Payment date in YYYY-MM-DD format | |
| payment_type | No | Payment method, e.g. "cash", "bank" | |
| proforma_invoice_id | No | Proforma invoice ID to link the payment to | |
| supplier_invoice_id | No | Supplier invoice ID to link the payment to (use for payments to suppliers) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It discloses mutation intent and the exactly-one-link constraint, but omits permissions, duplicate handling, reversibility, and response/error behavior for a create 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?
Three sentences, front-loaded with purpose, then the linking constraint, then the amount workflow. There is no filler, and each sentence adds actionable 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?
Covers the essential linking constraint and amount guidance for a 9-parameter mutation, but with no annotations or output schema it leaves out post-create behavior, failure modes, and permission expectations. Adequate but not fully 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?
Schema description coverage is 100%, so the baseline would be 3. The description adds value beyond the schema by stating the exactly-one-of relationship among the four link IDs and explaining how to handle full settlement amounts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Record') and resource ('payment'), and enumerates the four document types the payment can link to. It clearly distinguishes the create action from search/update/delete siblings, though it does not explicitly contrast with create_receipt.
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?
Specifies the key cross-field rule that exactly one of invoice_id, proforma_invoice_id, order_id, or supplier_invoice_id must be supplied. It also gives the full-payment workflow of reading outstanding balance first via get_invoice, but does not explicitly discuss when to choose update_payment or create_receipt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new product or service in the account.
| Name | Required | Description | Default |
|---|---|---|---|
| vat | No | VAT percentage, e.g. "19", "9", "0" | |
| code | No | Product code (optional) | |
| unit | No | Unit of measure, e.g. "buc", "ore", "luna" | |
| price | No | Unit price excluding VAT | |
| barcode | No | Barcode | |
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| quantity | No | Default quantity when adding the product to a document (optional) | |
| description | Yes | Product name / description | |
| product_kind | No | goods, service or consumable; a service cannot be stock-tracked | |
| stock_tracked | No | Track this product's stock (stock management module) | |
| min_stock_level | No | Minimum stock level; at or below it the product counts as low on stock | |
| default_stock_warehouse_id | No | Warehouse a document line books against when none is given (from list_stock_warehouses) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden, yet it says nothing about permissions, whether the call is idempotent, what happens on duplicate codes/barcodes, or how vat/price interact. For a 12-parameter mutation tool this leaves significant unstated behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single front-loaded sentence with zero waste, but the extreme brevity for a 12-parameter creation tool reads as under-specification rather than tightness. Nothing misleading, just too little.
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 12 parameters, no annotations, and no output schema, the description does not tell the agent what a successful creation returns (e.g., an id) or which fields become required downstream. The schema covers fields, but nothing covers outcome or constraints at the tool level.
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%, with clear per-field notes including helpful hints such as 'a service cannot be stock-tracked' and the reference to list_stock_warehouses. The description itself adds nothing to parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a new product or service') and clarifies the scope ('in the account'), so an agent knows exactly what object is being created. It does not explicitly differentiate from sibling tools like update_product or search_products, but the name plus this sentence is unambiguous against the other create_* siblings.
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?
There is no guidance on when to use this versus update_product, search_products, or delete_product, and no prerequisites such as required currency/description or the fact that stock fields only apply when stock tracking is enabled. The agent must infer all usage conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new proforma invoice for a client.
| Name | Required | Description | Default |
|---|---|---|---|
| series | No | Proforma series name (uses account default if omitted; provide it when the default series has a wrong year or a clashing number) | |
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| due_days | No | Days until due | |
| client_id | No | Client ID | |
| client_city | No | Client city | |
| client_name | No | Client name (if client_id not known) | |
| document_date | No | Date in YYYY-MM-DD format (defaults to today) | |
| client_address | No | Client address | |
| client_country | No | Client country code | |
| document_positions | Yes | Line items | |
| document_series_counter | No | Number within the series (auto-incremented if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and says nothing about consequences: whether the created document is finalized/immutable, whether the series counter is consumed, how client_id vs. client_name resolution behaves, or what is returned. A one-line 'Create X' is not enough for a mutation tool with zero annotation coverage.
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?
Single front-loaded sentence with zero redundancy — efficient. It is under-specified rather than padded, so the terseness cost is charged under completeness, not here.
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?
Eleven parameters, two required, no annotations, no output schema, and no explanation of the client identification fallback (client_id vs. client_name/city/address/country) or of defaulted fields (document_date, due_days, series, counter). The schema covers individual fields but the description offers no orienting context for constructing a valid document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema itself is rich (notably the discount_rate gating rules and the series default behavior), so the schema does the heavy lifting. The description adds nothing about parameters, which is the expected baseline of 3 when coverage is complete.
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?
A specific verb+resource: 'Create a new proforma invoice'. The qualifier 'for a client' implicitly separates it from create_supplier_proforma_invoice, but no sibling is named explicitly, and the distinction from create_invoice (proforma vs. fiscal) is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to use a proforma instead of a real invoice, no prerequisites, no mention of what to do afterwards (e.g. send_document, submit to e-factura). The only hint is 'for a client', which is far too thin for an 11-parameter creation tool in a family of ~10 create_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a receipt (chitanță) recording a received amount. A receipt has NO line items — it records a single amount, optionally linked to an invoice it pays.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Amount received (the receipt value) | |
| series | No | Receipt series name (uses account default if omitted; call list_series to find a valid name for the document year) | |
| currency | Yes | Currency code, e.g. "RON" | |
| client_id | No | Client ID (when not linking an invoice) | |
| invoice_id | No | Invoice this receipt pays (optional; when set, client and invoice details are copied from it) | |
| client_city | No | Client city | |
| client_name | No | Client name (when not linking an invoice) | |
| document_date | No | Date in YYYY-MM-DD format (defaults to today) | |
| client_address | No | Client address | |
| client_country | No | Client country code | |
| document_series_counter | No | Number within the series (auto-incremented if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It does disclose one real behavioral trait (no line items, details copied from the linked invoice), but says nothing about numbering side effects, whether creation is irreversible, or permission requirements. The schema's auto-increment/default notes compensate partially, leaving a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the resource definition front-loaded and the most distinguishing constraint (no line items) placed second and emphasized. Nothing is wasted.
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 an 11-parameter creation tool with no annotations and no output schema, the pairing of a clear description and fully documented schema is nearly sufficient. Minor gap: no statement of what the call returns (e.g., generated document ID or series counter), which an agent creating then referencing the receipt would want.
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 all 11 parameters are already documented, including the invoice_id copy behavior and series/date defaults. The description adds no syntax or format detail beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a receipt') and immediately draws the key distinction from sibling document tools: 'A receipt has NO line items — it records a single amount, optionally linked to an invoice it pays.' An agent can separate create_receipt from create_invoice/create_payment on substance, not just name.
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 phrase 'optionally linked to an invoice it pays' implies the use case (recording a payment against an invoice) but never explicitly says when to choose this over create_payment or create_invoice, nor any prerequisites. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new simplified supplier invoice (factură simplificată de la furnizor). Provide supplier_id when the supplier already exists, or supplier_name + address fields to create it on the fly.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| due_date | No | Payment due date in YYYY-MM-DD format (optional) | |
| supplier_id | No | Supplier ID (from search_suppliers). Takes priority over supplier_name. | |
| supplier_uid | No | Supplier fiscal code / CUI / VAT number (optional) | |
| document_date | No | Document date in YYYY-MM-DD format | |
| supplier_city | No | Supplier city | |
| supplier_name | No | Supplier name. If supplier_id is absent and the supplier does not yet exist, a new supplier is created automatically when address, city, and country are also provided. | |
| invoice_number | Yes | Invoice number as printed on the supplier's document, e.g. "FACT-123". Required by the API. | |
| supplier_address | No | Supplier street address | |
| supplier_country | No | Supplier country code, e.g. "RO" | |
| document_positions | Yes | Line items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose one important side effect: a new supplier record may be created implicitly during this call. It says nothing about validation behavior (duplicate invoice numbers, currency rules), permissions, or irreversibility of the write, which are notable gaps for an unannotated mutation tool.
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 tightly written sentences, front-loaded with the action and followed by the one non-obvious branch. No filler, though the parenthetical Romanian translation is optional and the description is short relative to the tool's complexity.
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 an 11-parameter, unannotated write tool with no output schema, the description covers the trickiest input path (implicit supplier creation) but leaves out required-field expectations, what 'simplified' means legally/practically versus a regular supplier invoice, and any indication of the returned result. Adequate but incomplete for this complexity.
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 schema already documents all 11 parameters, including the supplier_id-vs-supplier_name precedence and the discount_rate gating rules. The description restates the precedence and on-the-fly supplier creation but adds no format or constraint detail beyond it; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new simplified supplier invoice') plus the Romanian domain term, so the operation is unambiguous. However, it never distinguishes this from its near-identical siblings create_supplier_invoice and create_supplier_proforma_invoice, so an agent cannot tell what makes a 'simplified' invoice different without opening schemas.
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 second sentence gives useful conditional guidance on inputs ('Provide supplier_id when the supplier already exists, or supplier_name + address fields to create it on the fly'), which is real branching logic. But it offers no when-to-use/when-not guidance relative to the other supplier-invoice creation tools, which is the harder selection problem here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new supplier in the account.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | No | Fiscal code / CUI / VAT number (optional) | |
| city | Yes | City | |
| name | Yes | Supplier full name or company name | |
| No | Email address (optional) | ||
| address | Yes | Street address | |
| country | Yes | Country code, e.g. "RO", "DE" | |
| telephone | No | Phone number (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for a mutating tool, yet it discloses nothing beyond the bare action: no permission/auth requirements, no duplicate-handling or idempotency behavior for the uid, no statement of what is returned (e.g. the new supplier ID), and no reversibility note. "In the account" hints at scoping but that is the only added context.
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 front-loaded sentence with zero waste. It is efficient but so terse that brevity shades into under-specification rather than tight, informative prose.
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 creating mutation with 7 parameters, 4 required, no annotations and no output schema, the description should cover at minimum what happens on duplicate fiscal codes and what the caller gets back (the created supplier identifier). None of that is present, leaving real gaps an agent must guess at.
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 all seven fields including the optional uid, email and telephone are already documented in the schema. The description adds no meaning beyond that, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Create a new supplier") and scopes it to "the account". The intent is unambiguous, though it never names how it relates to siblings like create_supplier_invoice or update_supplier — the name alone carries that 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?
There is no guidance on when to use this versus update_supplier (for existing suppliers) or search_suppliers (to check for duplicates), and no prerequisites such as required account setup or unique fiscal code rules. The agent must infer all routing from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new supplier fiscal receipt (bon fiscal de la furnizor). Provide supplier_id when the supplier already exists, or supplier_name + address fields to create it on the fly.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| supplier_id | No | Supplier ID (from search_suppliers). Takes priority over supplier_name. | |
| supplier_uid | No | Supplier fiscal code / CUI / VAT number (optional) | |
| document_date | No | Receipt date in YYYY-MM-DD format | |
| supplier_city | No | Supplier city | |
| supplier_name | No | Supplier name. If supplier_id is absent and the supplier does not yet exist, a new supplier is created automatically when address, city, and country are also provided. | |
| receipt_number | Yes | Receipt number as printed on the fiscal receipt, e.g. "BON-42". Required by the API. | |
| supplier_address | No | Supplier street address | |
| supplier_country | No | Supplier country code, e.g. "RO" | |
| document_positions | Yes | Line items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It discloses the key side effect that a new supplier may be created automatically, but it omits other relevant traits for a create operation: duplicate handling, idempotency, validation behavior, and 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences, front-loaded with the core action and followed by the most important conditional behavior. Every sentence 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 create tool with 10 parameters, nested line items, and no output schema, the description covers only supplier resolution and leaves the receipt's required fields and line-item structure to the schema. It is minimally adequate given the rich schema, but thin for the tool's complexity.
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 baseline is 3. The description restates that supplier_id takes priority and that supplier_name plus address fields can auto-create a supplier, but these details are already present in the schema's parameter descriptions, so little extra meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and a clear resource ('supplier fiscal receipt'), including a Romanian synonym that disambiguates it from generic receipt tools. It does not explicitly contrast itself with siblings like create_receipt or create_supplier_invoice, so it stops short of full sibling 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?
It gives conditional guidance for supplier resolution (use supplier_id for existing suppliers, or supplier_name plus address fields to create one on the fly). However, it offers no guidance on when to choose this tool over sibling creation tools such as create_receipt or create_supplier_invoice, leaving tool selection implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new supplier invoice (purchase invoice). Provide supplier_id when the supplier already exists, or supplier_name + address fields to create it on the fly.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| due_date | No | Payment due date in YYYY-MM-DD format (optional) | |
| supplier_id | No | Supplier ID (from search_suppliers). Takes priority over supplier_name. | |
| supplier_uid | No | Supplier fiscal code / CUI / VAT number (optional) | |
| document_date | No | Invoice date in YYYY-MM-DD format | |
| supplier_city | No | Supplier city | |
| supplier_name | No | Supplier name. If supplier_id is absent and the supplier does not yet exist, a new supplier is created automatically when address, city, and country are also provided. | |
| invoice_number | Yes | Invoice number as printed on the supplier's document, e.g. "FACT-123". Required by the API. | |
| supplier_address | No | Supplier street address | |
| supplier_country | No | Supplier country code, e.g. "RO" | |
| document_positions | Yes | Line items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It does disclose a real side effect — a new supplier gets created automatically when address, city and country accompany supplier_name — which is the most valuable thing it could say. It says nothing about what happens on duplicate invoice numbers, what the call returns, or whether the document is only drafted versus finalized/submitted.
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, second sentence carrying the only branch that matters. Zero waste and no repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation with no annotations and no output schema, the description covers supplier resolution but not the response (does it return an ID? a document number?), nor prerequisites such as series selection or whether currency must match the supplier. The supplier branch is well handled; the rest of the call's contract is left to 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 description coverage is 100%, so all 11 parameters, including the nested line-item shape and the discount_rate gating logic, are already documented. The description's supplier_id priority and auto-create precondition largely restate the supplier_id and supplier_name schema descriptions rather than adding new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new supplier invoice') and disambiguates the term with '(purchase invoice)'. It clearly separates from create_invoice (client invoice) by naming the supplier domain, though it never names create_simplified_supplier_invoice or create_supplier_order, so the sibling distinction is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete selection criteria for the two supplier paths: pass supplier_id when the supplier exists, or supplier_name + address fields to create it on the fly. It lacks any statement of when NOT to use this tool (e.g. versus the simplified/non-fiscal supplier invoice variants), which keeps it out of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new supplier order (purchase order). Provide supplier_id when the supplier already exists, or supplier_name + address fields to create it on the fly.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| due_date | No | Expected delivery date in YYYY-MM-DD format (optional) | |
| supplier_id | No | Supplier ID (from search_suppliers). Takes priority over supplier_name. | |
| order_number | Yes | Order number as printed on the supplier's document, e.g. "CMD-123". Required by the API. | |
| supplier_uid | No | Supplier fiscal code / CUI / VAT number (optional) | |
| document_date | No | Order date in YYYY-MM-DD format | |
| supplier_city | No | Supplier city | |
| supplier_name | No | Supplier name. If supplier_id is absent and the supplier does not yet exist, a new supplier is created automatically when address, city, and country are also provided. | |
| supplier_address | No | Supplier street address | |
| supplier_country | No | Supplier country code, e.g. "RO" | |
| document_positions | Yes | Line items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the important auto-creation behavior for suppliers, but it omits permission requirements, side effects, duplicate handling, and what happens if supplier information is insufficient or omitted.
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 short sentences, front-loaded with the core action and immediately followed by the key supplier-resolution rule. There is no wasted text.
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 schema is rich and fully documented, which covers parameter-level completeness. However, with no annotations and no output schema, the description does not address prerequisites, return behavior, or selection against similar create tools, leaving meaningful contextual gaps for an 11-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. The description adds a helpful synthesis of the supplier_id versus supplier_name branch, but it does not add syntax or semantic detail beyond what the schema 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?
The description states a specific verb and resource: "Create a new supplier order (purchase order)." This clearly distinguishes it from generic order creation, though it does not explicitly name or contrast with close siblings such as create_order or create_supplier_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 gives useful branching guidance for supplier resolution: use supplier_id when the supplier exists, or supplier_name plus address fields to create one on the fly. However, it does not say when to choose this tool over siblings like create_order or create_supplier_invoice, nor does it state exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new supplier proforma invoice. Provide supplier_id when the supplier already exists, or supplier_name + address fields to create it on the fly.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | Currency code, e.g. "RON", "EUR" | |
| due_date | No | Payment due date in YYYY-MM-DD format (optional) | |
| supplier_id | No | Supplier ID (from search_suppliers). Takes priority over supplier_name. | |
| supplier_uid | No | Supplier fiscal code / CUI / VAT number (optional) | |
| document_date | No | Proforma date in YYYY-MM-DD format | |
| supplier_city | No | Supplier city | |
| supplier_name | No | Supplier name. If supplier_id is absent and the supplier does not yet exist, a new supplier is created automatically when address, city, and country are also provided. | |
| proforma_number | Yes | Proforma number as printed on the supplier's document, e.g. "PRO-123". Required by the API. | |
| supplier_address | No | Supplier street address | |
| supplier_country | No | Supplier country code, e.g. "RO" | |
| document_positions | Yes | Line items |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden. It does disclose a meaningful side effect — that a new supplier record is created automatically when supplier_name plus address fields are supplied — which the agent would otherwise have to infer from the schema. It says nothing about permissions, validation failures, whether duplicates are rejected, or what the call returns.
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 short sentences with no filler: the purpose leads and the supplier-identification rule follows immediately. Nothing in it is wasted, though it is arguably a touch thin for a multi-parameter mutation tool.
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 mutation tool with zero annotations and no output schema, the description should say more. It covers the one non-obvious behavior (supplier auto-creation) but leaves required-field expectations, failure modes, and return shape unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 11 parameters, including the supplier_id-takes-priority rule and the address/city/country requirement for auto-creation. The description restates this logic at a high level without adding format, ordering, or edge-case detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Create a new supplier proforma invoice.' The 'supplier' qualifier implicitly separates it from the sibling create_proforma_invoice, but the description never makes that distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description distinguishes the two supplier-identification paths (existing supplier_id vs. on-the-fly creation via supplier_name + address), which is useful routing guidance. It offers no guidance, however, on when to choose this tool over create_proforma_invoice, create_supplier_invoice, or create_simplified_supplier_invoice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a client by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Client ID (from search_clients) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden and it discloses almost nothing. 'Delete' implies a destructive, likely irreversible mutation, but the description never says whether the deletion cascades to invoices/orders/receipts referencing the client, whether it fails when such documents exist, whether confirmation is required, or what is returned.
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 six-word sentence that is front-loaded and waste-free — it is hard to be more concise. The economy comes at the cost of substance, which is penalized in other dimensions rather than here.
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 mutation with zero annotation coverage and no output schema, the definition is under-specified: an agent cannot tell whether deletion is safe, reversible, blocked by dependent documents, or what the response looks like. The schema fully covers the only parameter, but that is not enough for this risk profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is documented in the schema (including provenance from search_clients), so the baseline is 3. The description adds only the trivial restatement 'by ID' and nothing about ID format or behavior for unknown IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a client') plus the identifying key ('by ID'), which cleanly separates it from the many delete_* siblings that target invoices, orders, products, suppliers, etc. It doesn't explicitly name or contrast those siblings, so 4 rather than 5.
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?
There is no guidance on when to use this versus update_client, or versus deactivating a client, and no prerequisites or preconditions. The only implied usage is the ID parameter's parenthetical pointing at search_clients, which is a discovery hint rather than a usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice ID (from search_invoices) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says 'Delete' but does not state that the operation is irreversible, whether it cascades to related records, what permissions are required, or what happens to issued/e-factura 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 sentence is short and front-loaded with the action and resource, with no wasted words. It is perhaps overly terse for a destructive operation, but from a pure conciseness standpoint it is efficient.
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 no annotations and no output schema, this description is not complete enough. It should disclose irreversibility, side effects, and any restrictions on deleting invoices, especially given the many similar supplier/proforma invoice deletion siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains that the id is an invoice ID from search_invoices. The description merely repeats 'by ID' without adding format details, examples, or constraints, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (delete) and resource (invoice) plus the lookup key (ID), so an agent can tell what the tool does. It does not distinguish itself from the many sibling delete tools such as delete_supplier_invoice, delete_proforma_invoice, or delete_simplified_supplier_invoice, which is a meaningful gap in this family.
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?
There is no guidance on when to use this tool versus update_invoice, get_invoice, or the closely related delete_* siblings. It also omits any prerequisite conditions, such as whether the invoice must be in a particular state before deletion or what to do if it has already been issued or sent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an order by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Order ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for a destructive operation. It never says whether the deletion is permanent, what happens to related invoices/payments, what permissions are required, or what failure looks like when the ID is unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with zero padding. Nothing is wasted, though the terseness comes at the cost of the missing behavioral detail noted elsewhere.
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, unannotated tool with no output schema, the definition says nothing about irreversibility, side effects, or error conditions. An agent has to guess before firing a delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is already documented as 'Order ID'. The phrase 'by ID' adds nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Delete) and resource (order) plus the lookup key (ID), so an agent can instantly tell it apart from create_order, search_orders and the delete_* siblings. It stops short of 5 only because there is no further scope statement.
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?
There is no guidance on when to use this over search_orders or the update_* variants, and no prerequisites or exclusions. Being the sole order-deletion tool implies usage, but nothing is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a payment by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Payment ID (from search_payments) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It discloses only that the operation deletes by ID; it does not say whether deletion is irreversible, what permissions are required, whether related records are affected, or what happens if the ID does not 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 front-loaded sentence with no wasted words. It is efficiently structured, though its brevity leaves little room for operational context.
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 mutation with no annotations and no output schema, the description is too thin. An agent still lacks essential context about irreversibility, failure behavior, and prerequisites before invoking delete_payment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains that id is a Payment ID available from search_payments. The description adds only 'by ID' and does not meaningfully extend 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 states a specific verb and resource: delete a payment, scoped by ID. It is clear enough to distinguish from create_payment, update_payment, search_payments, and the many delete_* siblings by resource name, though it does not explicitly call out those alternatives.
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?
There is no guidance on when to use this tool versus search_payments, update_payment, or any other sibling, and no prerequisites or warnings are given. The description merely restates the operation implied by the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a product by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Product ID (from search_products) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden, and it discloses almost nothing: permanence of deletion, referential effects (e.g., a product referenced by existing invoices), required permissions, and error behavior on an unknown ID are all unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler, which is appropriate for a single-parameter tool. It is terse to the point of under-specification, but that is penalized under completeness rather than here.
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 one-parameter mutation with no annotations and no output schema, the description says nothing an agent needs beyond the operation name — no confirmation of what happens on success/failure or what collateral effects deletion has.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter is documented in the schema as a Product ID sourced from search_products. The description's 'by ID' adds nothing beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (product) with the identifying key (ID). It is unambiguously distinguishable from siblings such as delete_client or delete_invoice, though it does not explicitly contrast with update_product.
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?
There is no guidance on when to use this versus update_product or search_products, no prerequisites, and no mention of confirmation or irreversibility. The only hint of context is the schema note that the ID comes from search_products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a proforma invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Proforma invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure for a destructive operation — yet it says nothing about irreversibility, required permissions, whether linked records are affected, or behavior when the ID does not exist. The verb 'delete' only implies mutation; no additional behavioral context was added.
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 short sentence with no filler, and the resource and identifier come first. Nothing is wasted; the gap is under-specification rather than 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?
For a one-parameter destructive tool with no annotations and no output schema, the description should at minimum cover irreversibility, error behavior on unknown IDs, and its distinction from delete_supplier_proforma_invoice. None of that is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter and the schema documents it fully (100% coverage) as 'Proforma invoice ID'. The description's 'by ID' adds no meaning beyond the schema, which is the expected baseline for a single well-documented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a proforma invoice') plus the identifier used, so the agent knows exactly what the tool does. It does not differentiate itself from the sibling delete_supplier_proforma_invoice, which is a real ambiguity risk given the near-identical name.
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?
No guidance on when to use this versus delete_supplier_proforma_invoice, no prerequisites, and no note that the ID likely comes from search_proforma_invoices. The agent must infer everything about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a receipt by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Receipt ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does not meet it. It never states that deletion is irreversible, whether it cascades to related documents, what permissions are required, or what happens on a nonexistent ID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler. Its brevity is efficient rather than padded, though the terseness leaves the gaps noted in other dimensions.
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 single-record operation with zero annotations and no output schema, the description should disclose irreversibility and error behavior. Neither is present, leaving the agent without the context needed to call it safely.
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 single 'id' parameter is fully documented in the schema. The description's 'by ID' merely restates this, adding no format or sourcing detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a receipt') scoped by ID, which is enough to tell it apart from search_receipts and the create_receipt sibling. It stops short of any explicit sibling differentiation, but the resource name does the disambiguating work.
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?
No guidance on when to use this versus alternatives, no prerequisite that the ID be obtained via search_receipts, and no mention of confirmation or preconditions. The agent must infer the entire workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a simplified supplier invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Simplified supplier invoice ID (from search_simplified_supplier_invoices) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not disclose that deletion is irreversible, whether related records are cascaded or orphaned, required permissions, or the response on success/failure — significant gaps for a destructive mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and resource, no filler. It is as short as it can be while still naming the resource.
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 operation with no annotations and no output schema, the description should at minimum convey irreversibility and any eligibility constraints. It supplies only the minimal 'what', leaving an agent unable to judge consequences.
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 id parameter has 100% schema coverage, including where to obtain it (search_simplified_supplier_invoices). The description adds nothing beyond what the schema already says, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Delete) and resource (simplified supplier invoice) with the identifying key. It implicitly contrasts with delete_supplier_invoice, but never names that sibling explicitly, so the distinction rests on the reader noticing the 'simplified' qualifier.
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 no conditions for when to use this versus delete_supplier_invoice or other delete tools, and no prerequisites. Usage must be inferred entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a supplier by ID. Refuses if the supplier still has linked documents (which would be orphaned) unless force is true.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier ID (from search_suppliers) | |
| force | No | Delete even when the supplier has linked documents (they will keep the supplier name but point at a deleted supplier). Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and successfully discloses the key risk: deletion is blocked when linked documents exist, which would otherwise be orphaned, and force overrides this. It doesn't mention required permissions, irreversibility, or expected response, but it covers the most important safety nuance an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the action and immediately followed by the critical refusal condition. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter destructive tool with no output schema and no annotations, the description covers purpose and the main behavioral gotcha. It could be more complete by noting irreversibility or permissions, but the essential information for a correct call is present.
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 both parameters (id, force) are already well documented. The description reinforces the force condition but adds no new syntax, format, or meaning beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('a supplier by ID'), making the operation unambiguous. It does not explicitly differentiate from sibling delete tools, but the name and text leave no confusion about which resource is affected.
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 implies when to use the tool (to delete a supplier) and gives one when-not condition: linked documents cause refusal unless force is true. However, it doesn't reference finding the ID via search_suppliers in the description (only in the schema) or suggest alternatives like updating the supplier instead of deleting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a supplier fiscal receipt by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier fiscal receipt ID (from search_supplier_fiscal_receipts) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says the tool deletes a receipt. It does not disclose irreversibility, permission requirements, confirmation needs, side effects, or behavior when the ID is missing.
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 front-loaded sentence with no filler. It is structurally clean, though extremely sparse given the destructive nature of the tool.
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 mutation with no annotations and no output schema, the description provides almost no behavioral or safety context. The single parameter is well documented, but an agent lacks enough information to invoke the tool confidently and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents the ID and its source. The description merely restates 'by ID,' adding no further parameter 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 states a specific verb (delete) and resource (supplier fiscal receipt), plus the required identifier. It is distinguishable from search_supplier_fiscal_receipts and other delete_* siblings by resource, though it does not explicitly mention alternatives.
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?
There is no guidance on when to use this tool versus search_supplier_fiscal_receipts, update tools, or other delete variants. The only hint that the ID comes from search_supplier_fiscal_receipts appears in the schema, not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a supplier invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier invoice ID (from search_supplier_invoices) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. For an irreversible destructive operation it discloses only that deletion happens — nothing about permanence, required permissions, side effects on linked records, or failure modes for invoices already sent to e-Factura. This is a serious gap for a delete tool with zero annotation coverage.
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 front-loaded sentence with no wasted words, correctly sized for a one-parameter tool. The brevity is efficient rather than padded, though it edges toward under-specification given the destructive nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and a destructive single-param operation, the description should say what happens on success/failure and that the action is irreversible. None of that is present, leaving an agent unable to judge the consequences of calling 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?
Schema description coverage is 100% and the single parameter already documents its origin ("from search_supplier_invoices"). The description's "by ID" adds nothing beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("Delete a supplier invoice") and scopes it to an ID lookup, which is enough to distinguish it from the many other delete_* siblings (delete_invoice, delete_supplier, delete_supplier_order). It does not explicitly say how it differs from adjacent supplier-document deletes, but the resource name carries the distinction.
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?
There is no guidance on when to use this versus delete_simplified_supplier_invoice, delete_supplier_fiscal_receipt, or the other supplier-document deletes, and no mention of prerequisites such as the invoice needing to exist or not be submitted to e-Factura. The only implied usage is "you have an ID and want it gone."
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a supplier order by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier order ID (from search_supplier_orders) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries full behavioral burden, yet it says nothing beyond the mutation itself. It omits irreversibility, whether linked documents block deletion, required permissions, and what is returned on success or failure.
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 front-loaded sentence with zero filler. It is efficient, though its brevity borders on under-specification rather than genuine economy.
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, irreversible operation with no annotations and no output schema, the description should disclose consequences, dependency constraints, and response behavior. Those are entirely absent, leaving the agent unprepared for failure modes.
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?
Only one parameter and schema description coverage is 100%; the schema already documents 'id' and even its provenance ('from search_supplier_orders'). The description adds nothing further, 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?
States a specific verb ('Delete') and resource ('a supplier order') scoped by ID, which distinguishes it from delete_order, delete_supplier_invoice and other delete_* siblings. No explicit sibling routing, but the resource noun is 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?
There is no guidance on when to use this versus soft-cancel or archival alternatives, no prerequisites (e.g., that the order must be draft/uninvoiced), and no exclusions. The agent is left to infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a supplier proforma invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier proforma invoice ID (from search_supplier_proforma_invoices) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, and it only says 'delete'. It does not state whether deletion is permanent or reversible, what happens to linked records, whether it requires special permissions, or what is returned on success or failure — all critical for an irreversible mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the action and scoping front-loaded and no wasted words. It is efficient, though being this terse contributes to the behavioral gaps noted elsewhere.
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, irreversible operation with zero annotations and no output schema, the description should explain consequences, confirmations, or failure modes. None of that is present, so an agent cannot predict the effect of calling it beyond 'something gets deleted'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema itself explains that the ID comes from search_supplier_proforma_invoices. The description's 'by ID' adds no meaning beyond that, so the high-coverage baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (delete) and a precise resource (supplier proforma invoice) scoped by ID, which cleanly separates it from delete_proforma_invoice and delete_supplier_invoice by name alone. It stops short of any explicit differentiation sentence, but the resource name is 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?
There is no guidance on when to use this versus the sibling delete tools, nor any prerequisite such as looking the invoice up via search_supplier_proforma_invoices first. The only hint toward usage is incidental, appearing in the schema's parameter description rather than the tool description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate and return the UBL 2.1 XML for an invoice in e-Factura format using its stored e-Factura properties. Does NOT submit to ANAF.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does useful work by clarifying this is a local generation step with no side effect on ANAF. However it omits what happens when the invoice lacks stored e-Factura properties, whether the XML is persisted to disk, and whether any permission/validation can fail.
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 short sentences with zero filler; the core action leads and the disambiguating constraint follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description tells the agent the return value (UBL 2.1 XML) and the non-submission behavior. Missing only edge-case behavior (missing properties, error output), which is a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single required parameter, so the baseline is 3; the description adds that invoice_id selects the invoice whose stored e-Factura properties are serialized, which is meaning beyond 'Invoice ID'. No format/example detail is given, so not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and artifact ('Generate and return the UBL 2.1 XML') tied to a specific resource ('an invoice in e-Factura format'), and explicitly scopes the source of data ('using its stored e-Factura properties'). It also carves itself away from the submission sibling with 'Does NOT submit to ANAF.'
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 negative clause 'Does NOT submit to ANAF' effectively routes the agent to submit_invoice_to_efactura for filing and to this tool for local XML retrieval. It gives clear context but never names the alternative tool or states prerequisites (e.g. that e-Factura properties must already be populated).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the PDF of a document (invoice, proforma invoice, receipt, order, or notice) as a base64-encoded string. The caller can decode the base64 and save it as a .pdf file. Defaults to document_type "invoice".
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID | |
| document_type | No | Document type: invoice (default), proforma_invoice, receipt, order, notice |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does disclose the non-obvious output shape (base64 string, intended for decoding to a .pdf) and the default type, but says nothing about failure modes, whether id must belong to the selected document type, auth requirements, or document size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the return type and resource, with zero filler. The final sentence restates information already present in the schema's document_type description, a minor 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?
With only two flat parameters, no output schema, and no nested objects, the description covers what an agent needs: the resource, the return encoding, and the type default. Remaining gaps (id must match the chosen document type, error behavior) are minor for a straightforward read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description repeats the enum of document types and the 'invoice' default that the schema already documents and adds no syntax, format, or cross-parameter constraint beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the PDF of a document') plus its serialization ('base64-encoded string') and enumerates the five supported document types, so an agent can distinguish this PDF-fetch tool from metadata siblings like get_invoice. It never names a sibling explicitly, so differentiation is inferred rather than stated.
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 use case ('The caller can decode the base64 and save it as a .pdf file') and states the default document_type, which is genuine usage context. However, it gives no explicit when-to-use/when-not guidance, no pointer to get_invoice for metadata instead of a file, and no note about matching the id to the right document_type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the ANAF e-Factura SPV submission status of an invoice. Returns submission/download indexes and the ANAF stare (ok/nok) of the current submission from stored transactions; null while ANAF is still judging it.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does meaningful work by disclosing that results come from stored transactions, that it returns submission/download indexes, the ANAF stare ok/nok, and that null is returned while ANAF is still judging. It does not explicitly state read-only behavior, permissions, or freshness limits beyond the stored-transactions hint.
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 front-loaded with the core purpose. The second clause adds useful return-value and null-state context without unnecessary text.
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 there is no output schema and no annotations, the description does well by explaining what is returned and the null pending state. It is only slightly incomplete because it does not clarify the relationship to refresh_efactura_status or the freshness guarantees of stored transactions.
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% for the single invoice_id parameter, so the schema already carries the parameter documentation burden. The description reinforces that the status is for an invoice but adds no syntax, format, or validation detail 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 states a specific verb and resource: get the ANAF e-Factura SPV submission status of an invoice. It also clarifies that the status comes from stored transactions, which helps distinguish it from a refresh operation. However, it does not explicitly name or contrast with the sibling tool refresh_efactura_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use, checking an invoice's stored e-Factura status, is implied clearly enough. But there is no explicit guidance on when to use this tool versus refresh_efactura_status or submit_invoice_to_efactura, and no stated exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single invoice by ID, including its line items (positions) and payments.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice ID (from search_invoices) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It helpfully discloses that the response embeds line items and payments (compensating for the absent output schema), but says nothing about read-only semantics, behavior when the ID is unknown, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler; the operation and the returned data are front-loaded and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no annotations and no output schema, the description covers what the tool fetches and roughly what comes back (line items, payments). Missing only edge-case behavior such as not-found handling.
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?
Only one parameter, and the schema documents it at 100% coverage including provenance from search_invoices. The description's 'by ID' restates rather than extends the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Get a single invoice by ID' — and adds the payload contents (line items and payments). This distinguishes it from search_invoices well enough, though it never names the alternative explicitly.
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?
'by ID' implies you must already have an identifier, and the schema notes the ID comes from search_invoices, but that routing information lives in the schema rather than the description. No explicit when-to-use or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single supplier document by ID, including its line items (positions) and payments. Use this to read a supplier invoice's positions before copying them to another document type (e.g. converting a supplier invoice to a supplier fiscal receipt). Valid document_type values: supplier_invoice (default), supplier_order, supplier_proforma_invoice, supplier_fiscal_receipt, simplified_supplier_invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier document ID | |
| document_type | No | Document type (default: supplier_invoice) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only retrieval and discloses the returned payload shape (positions, payments), which is valuable, but says nothing about permissions, error behavior for unknown IDs, or whether related nested data can be large/truncated.
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 plus an enumerated value list, all front-loaded with the action and return contents. Slightly dense, but every clause (return shape, use case, allowed document types) 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 2-parameter read tool with no output schema, the description adequately covers what the call returns and the valid type values. Missing only failure/handling notes, which limits it below a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3. The description adds real value by enumerating the valid document_type values (supplier_invoice default, supplier_order, supplier_proforma_invoice, supplier_fiscal_receipt, simplified_supplier_invoice), which the schema does not constrain via enum.
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?
Specific verb+resource ('Get a single supplier document by ID') plus an explicit statement of what is returned (line items/positions and payments). This clearly distinguishes it from the sibling search_* and list_* tools, which retrieve collections rather than one document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete use case: reading an invoice's positions before copying them to another document type, with a conversion example. It does not explicitly say when NOT to use it (e.g. use search_supplier_invoices for browsing), but the retrieval-by-ID framing makes the boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate invoice totals without returning raw records. Returns count plus per-currency sums (gross total, taxable base, VAT) grouped by the chosen dimension — sums are never mixed across currencies. Much cheaper than search_invoices + manual aggregation.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Document state filter: draft, open, closed, cancelled, or the alias "issued" (= open+closed). Defaults to "issued", so draft and cancelled invoices are excluded from the figures. Pass "all" to include every state. | |
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| currency | No | Restrict to one currency before grouping | |
| group_by | No | Grouping dimension: "month" (default), "year", "client", "state", "currency" | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses that no raw records are returned, that sums are never mixed across currencies, and that results are grouped by the selected dimension. It omits cost/permission context and what an empty result looks like, keeping it short of 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, then output shape, then the cost rationale. No filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description compensates by spelling out the return shape (count plus gross total, taxable base and VAT per currency, grouped by dimension). Slightly short of complete since the exact grouped-result keys and empty-result behavior are unspecified.
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 each parameter already documents its semantics (including the 'issued' alias and default), so the baseline of 3 applies. The description reinforces the grouping and currency-restriction concepts but adds no format or edge-case detail 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?
States a specific verb and resource ('Aggregate invoice totals') plus a decisive negative scope ('without returning raw records'), which instantly separates it from the search_* siblings. An agent can tell what it produces (count + per-currency sums grouped by a dimension) without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent away from 'search_invoices + manual aggregation' by framing this as the cheap alternative, which is a real when-to-use signal. It does not, however, distinguish itself from nearby report_* siblings (report_invoiced_by_period, report_vat_collected) that could plausibly overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supplier invoices received via ANAF SPV (e-Factura). Filters to supplier invoices that have efactura submission or download indexes, indicating they were received through SPV.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results (default: 20, max: 100) | |
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full disclosure burden. It does add a genuinely useful behavioral fact: results are restricted to rows carrying efactura submission/download indexes. However, it says nothing about ordering, pagination behavior beyond the schema, or the read-only/scope constraints an agent would want to confirm.
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 purpose and followed by the one non-obvious qualification. Minimal waste, though the second sentence slightly restates the 'supplier invoices received' idea before adding the index 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?
For a simple zero-required-param list tool this is close to adequate, but with no annotations and no output schema the description would ideally state that it is a read-only operation and hint at what each returned record represents. The implicit-filter caveat is covered; the return shape and date-field semantics are not.
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 limit and both date bounds are already fully documented with defaults, max, and format. The description adds no additional filter semantics (e.g., which date field the range applies to — issue date vs. SPV receipt date), so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus the ingestion channel: 'List supplier invoices received via ANAF SPV (e-Factura)'. The second sentence clarifies the implicit filter, so the agent understands this is not a general supplier-invoice list. It does not explicitly differentiate itself from the nearby search_supplier_invoices / search_invoices siblings, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied — call this when you need invoices that arrived through the SPV channel — but there is no explicit when-to-use/when-not statement and no alternative tool is named. An agent must infer that search_supplier_invoices is the right pick for locally created supplier invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's document series (name, year, next number). Use this to pick a valid series for a document's year — creation fails with "Serie ... Anul seriei ... nu coincide cu data documentului" when the account default series belongs to a different year. Pass the chosen name as the create tool's series argument.
| Name | Required | Description | Default |
|---|---|---|---|
| document_type | No | Restrict to one type: invoice, proforma_invoice, order, notice, receipt. Omit to list all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden; it discloses the read-only listing behavior, the fields returned, and — valuably — the error condition that this tool exists to prevent in create_* calls. It does not cover pagination or permission requirements, which keeps it short of a 5 for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it returns, why it matters (with the exact error string for diagnosis), and the follow-up action. The purpose is front-loaded before the diagnostic 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?
There is no output schema, yet the description names the returned fields and how to use them downstream, and it links to the create tools that consume the result. For a single-optional-parameter list tool this is complete enough 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?
Schema description coverage is 100% for the single optional `document_type` parameter, including the enum-like value set; the description adds no syntax or behavioral detail beyond what the schema already states. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the account's document series') and names the returned fields (name, year, next number). No sibling tool lists series, and the description makes that scope 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?
Explicitly prescribes when to call it ('Use this to pick a valid series for a document's year'), explains the concrete failure mode that motivates it (the Romanian year-mismatch error), and names the downstream alternative ('Pass the chosen name as the create tool's `series` argument'). This is exactly the when/when-not guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an ANAF status (stareMesaj) check for an already-submitted invoice and return the current stored status. Use this after submit_invoice_to_efactura to advance the invoice toward its confirmed state. The check runs asynchronously, so if anaf_status is still null, call get_efactura_status again a few moments later for the updated result.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID to check |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It usefully discloses that the check runs asynchronously and that a null anaf_status means the result is not yet stored, but it says nothing about mutating stored state, ANAF-side throttling, authentication, or failure behavior for a tool that clearly writes a refreshed status back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action and then the workflow context; no filler. The closing sentence is slightly muddled by naming a different tool for the retry, which costs a bit of precision.
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 no output schema, it covers the essentials: what is triggered, when to call it, and that the returned status may lag. It leaves the shape of the returned status and its possible values unexplained, though with no output schema that gap is understandable.
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?
Only one parameter, invoice_id, with 100% schema description coverage ('Invoice ID to check'), so the schema already carries the semantics. The description adds nothing beyond it, which is the expected baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Start an ANAF status (stareMesaj) check for an already-submitted invoice.' It is distinguishable from get_efactura_status (which it names as the retrieval step), but the phrasing 'call get_efactura_status again' blurs the boundary between triggering a refresh and reading the stored result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear trigger condition ('Use this after submit_invoice_to_efactura') and a fallback path when the status is still null. It stops short of stating when this tool should not be used instead of get_efactura_status, so the two-step workflow must still be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate total invoiced amounts grouped by month and currency for a date range. Returns taxable base, VAT collected, and gross total per period/currency. Defaults to issued invoices only.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Document state filter: draft, open, closed, cancelled, or the alias "issued" (= open+closed). Defaults to "issued", so draft and cancelled invoices are excluded from the figures. Pass "all" to include every state. | |
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| currency | No | Restrict to one currency, e.g. "RON" | |
| group_by | No | Grouping granularity: "month" (default) or "year" | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully states that results default to issued invoices only and that the output includes taxable base, VAT collected, and gross total per period/currency, but it does not clarify read-only behavior, date-range defaults when omitted, or any other operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences with no wasted language. The core purpose and returned metrics are front-loaded, followed by the important default-state caveat.
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 report tool with no output schema, the description explains both the aggregation dimensions and the returned financial measures. It is nearly complete, though it leaves open what date range is used if date_from and date_to are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so the parameter baseline is 3. The description adds some meaning by framing the output as grouped by month and currency, but it does not add syntax or edge-case guidance beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: aggregate invoiced amounts, grouped by month and currency over a date range. It also names the returned measures, taxable base, VAT collected, and gross total, making the report's purpose distinguishable from sibling reports such as report_vat_collected or report_outstanding_balances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the report name and the statement that it aggregates invoiced amounts for a date range. However, it does not explicitly say when to choose this report over sibling reports like invoices_summary or report_vat_collected, nor does it state exclusions beyond the default issued-invoice filter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List outstanding invoice balances per client: sum of totalDue (invoice total minus payments already recorded) for issued invoices, grouped by client and currency. Use for aging reports and collections follow-up.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of clients to return (default 20) | |
| date_to | No | Filter invoices issued on or before this date (YYYY-MM-DD) | |
| currency | No | Restrict to one currency | |
| date_from | No | Filter invoices issued on or after this date (YYYY-MM-DD) | |
| client_name | No | Filter by client name (partial match) | |
| overdue_only | No | When true, only include invoices past their due date |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does meaningful work: it discloses that only issued invoices count, that payments already recorded are subtracted, and that results are grouped by client and currency. It leaves unstated the read-only nature (only implied by 'List'), result ordering, and whether pagination applies.
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, both earning their place: the first front-loads the operation and its exact computation, the second supplies the use case. No filler or repetition of the tool name.
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 six-parameter read-only aggregation with no output schema, the description conveys what is computed and how it is grouped, which is what an agent needs to call it correctly. Missing are result ordering and the shape of the returned per-client rows, which matter somewhat given no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds the aggregation semantics that the schema cannot express: what counts as 'outstanding' and how grouping works. It still does not connect the date filters to the 'issued on' basis the way the schema does, so the added value is meaningful but partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List outstanding invoice balances per client'), then defines the metric precisely as sum of totalDue minus recorded payments for issued invoices, grouped by client and currency. This is clearly distinguishable from siblings like report_payments_vs_invoiced, report_invoiced_by_period, and invoices_summary.
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 names two use cases ('aging reports and collections follow-up'), which gives the agent a solid selection signal. It does not name an alternative tool or a when-not-to-use condition, so it falls short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare total invoiced (issued invoices by document date) vs total collected (payments by payment date) per month and currency. Shows collection rate and cash flow gap.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Document state filter: draft, open, closed, cancelled, or the alias "issued" (= open+closed). Defaults to "issued", so draft and cancelled invoices are excluded from the figures. Pass "all" to include every state. | |
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| currency | No | Restrict to one currency | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It adds useful behavioral detail about the metric definitions (document date vs payment date) and the derived outputs (collection rate, cash flow gap), but does not state that this is a read-only aggregation, the response shape, or any performance considerations.
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 tightly written sentences with zero waste, front-loading the comparison and then the derived outputs. 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 no-output-schema, no-annotation reporting tool with four optional params, the description covers the metric definitions but leaves the return structure, granularity behavior (e.g., empty months), and read-only nature implicit. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself explains the 'issued' alias default and date semantics well. The description reinforces the date-basis distinction (invoiced by document date, collected by payment date), but adds little 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.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific comparative operation: total invoiced (by document date) vs total collected (by payment date), per month and currency. This clearly distinguishes it from single-metric siblings like report_invoiced_by_period or report_vat_collected, though it does not explicitly name those alternatives.
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 purpose implies usage (measuring collection rate and cash flow gap over time), but there is no explicit when-to-use guidance, no exclusions, and no routing to the closely related report_outstanding_balances or report_invoiced_by_period siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank clients by total invoiced amount in a date range. Returns client name, total amount, and invoice count per currency, sorted descending.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of top clients to return (default 10) | |
| state | No | Document state filter: draft, open, closed, cancelled, or the alias "issued" (= open+closed). Defaults to "issued", so draft and cancelled invoices are excluded from the figures. Pass "all" to include every state. | |
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| currency | No | Restrict to one currency | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it usefully discloses the return fields, descending sort, and that totals are kept per currency rather than converted into one figure. It does not mention read-only safety, default filtering of draft/cancelled documents, or behavior when currency is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no waste; the ranking purpose and the date-range scoping come first, followed by the returned fields. Nothing is repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only analytics tool with no output schema, the description adequately explains what comes back and in what order. It could still note the default top-10 limit and the default "issued" state filter, but the schema covers both.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameters are well documented there, including the "issued" state alias and inclusive date bounds, so the baseline applies. The description only gestures at "date range" and "per currency" and adds no syntax or default information 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?
States a specific verb and resource ("Rank clients by total invoiced amount") plus the aggregation scope (date range) and output shape (name, total, invoice count, sorted descending). That is enough to separate it from report_invoiced_by_period or invoices_summary, though it never names those siblings explicitly.
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?
No when-to-use or when-not-to-use guidance and no mention of alternatives among the many report_* and search_* siblings. The only contextual cue is the implicit date-range filter, so an agent must infer selection from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Monthly output VAT summary for the VAT return (decont TVA): taxable base and VAT collected per month from issued invoices. Drafts and cancelled invoices are excluded by default. For per-rate breakdown (19%/9%/5%) use get_invoice on individual invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Document state filter: draft, open, closed, cancelled, or the alias "issued" (= open+closed). Defaults to "issued", so draft and cancelled invoices are excluded from the figures. Pass "all" to include every state. | |
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| currency | No | Restrict to one currency (default: all) | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It usefully discloses that drafts and cancelled invoices are excluded by default and that it aggregates per month, and it points to get_invoice for rate detail. However it does not describe the return shape, date-range defaults, currency behavior, or whether figures are reversible/recomputable – gaps that matter for a report with no output 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?
Three tight sentences with zero waste: purpose first, then default exclusion behavior, then the alternative pointer. 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations and no output schema, so the description must define the return and safety profile. It covers scope, exclusions, and an alternative, but omits the return structure (taxable base vs. collected columns, units) and date-range defaults. Adequate but with clear gaps given the absence of an output 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 all four parameters (state, date_from, date_to, currency) are already fully documented in the schema. The description reinforces the state default ('Drafts and cancelled invoices are excluded by default'), aligning with the 'issued' default, but adds no syntax or format detail beyond the schema. 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 opens with a specific verb+resource: 'Monthly output VAT summary for the VAT return (decont TVA): taxable base and VAT collected per month from issued invoices.' An agent can immediately distinguish this reporting tool from the write/create siblings and from report_vat_deductible, which handles the deductible side.
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 states usage context ('for the VAT return') and routes the agent to an alternative for per-rate detail: 'use get_invoice on individual invoices.' It also notes the default exclusion of drafts/cancelled. It stops short of contrasting with report_vat_deductible or report_invoiced_by_period, so there is a minor gap for full when/when-not disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Monthly input VAT summary from supplier invoices (TVA deductibilă for decont TVA): taxable base and input VAT paid per month.
| Name | Required | Description | Default |
|---|---|---|---|
| date_to | No | End date inclusive (YYYY-MM-DD) | |
| currency | No | Restrict to one currency (default: all) | |
| date_from | No | Start date inclusive (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It does disclose the aggregation granularity ('per month'), the source set (supplier invoices), and the output content (taxable base, input VAT paid), which is meaningful behavioral context. However, it omits relevant traits: it never states the operation is a read-only report, what happens when date bounds are omitted, how currency filtering affects aggregation, or whether unpaid invoices are included.
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 front-loaded sentence that identifies the report, its data source, its output fields, and its regulatory context with no waste. Appropriate sizing for a three-parameter report tool.
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 partially compensates for the absent output schema by naming the returned metrics (taxable base, input VAT per month). But with all three parameters optional and no annotations, it leaves a real gap: an agent calling with no arguments cannot know the default period or whether currency defaults to all, which the schema's '(default: all)' only covers for currency.
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 date_from, date_to, and currency are already documented in the schema. The description adds nothing about parameter behavior beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource and scope: monthly input VAT (TVA deductibilă) aggregated from supplier invoices, returning taxable base and input VAT. This implicitly separates it from report_vat_collected (output/collected VAT), though no sibling is named explicitly.
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 phrase 'for decont TVA' implies the use case (Romanian VAT return preparation) and 'supplier invoices' implies the data source, but there is no explicit when-to-use, when-not, or reference to the sibling report_vat_collected. Usage must be inferred from domain vocabulary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for clients by id, name, email, uid (VAT/CUI), or telephone. Results are returned newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Client ID — returns that exact client | |
| uid | No | Client fiscal code / CUI / VAT number | |
| name | No | Client name (partial match) | |
| No | Client email address | ||
| limit | No | Maximum results, newest first (default 20) | |
| telephone | No | Client phone number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden; it does disclose result ordering ('newest first'), which is genuine behavioral value. However it omits whether criteria are ANDed or ORed, whether matching is exact vs partial beyond the name hint, and whether the result set is bounded by anything other than limit.
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, no filler, with the searchable fields and the ordering guarantee front-loaded. Nothing repeats the schema verbatim in a wasteful way.
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 what can be searched and the sort order, which is the core of a lookup tool with no output schema or annotations. It still leaves the agent guessing about multi-filter combination logic and whether an unfiltered call is valid, which matters for a 6-parameter all-optional 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 description coverage is 100%, so each parameter is already documented (including partial match on name and the limit default of 20). The description restates the field list but adds no extra semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('clients') and enumerates the searchable fields (id, name, email, uid, telephone), making the scope concrete. It differentiates itself from the many create_/delete_/update_ siblings by resource name, but offers no explicit contrast with adjacent read tools like search_suppliers or count_records.
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?
No guidance on when to use this versus siblings such as search_suppliers, count_records, or report_top_clients. It also does not say what happens when no filters are supplied (implied: returns all clients, capped by limit), which is the most important invocation decision for a zero-required-param tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search invoices with rich filtering and cursor-style pagination. Returns { items, page, per_page, has_more }. Items are slim by default (no positions); set include_positions: true when line items are needed.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| sort | No | Sort field: documentDate (default), dueDate, total, series, id | |
| order | No | Sort direction: desc (default) or asc | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| series | No | Filter by invoice series (exact match) | |
| date_to | No | Document date <= (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| client_id | No | Filter by exact client ID (more efficient than client_name) | |
| date_from | No | Document date >= (YYYY-MM-DD) | |
| max_total | No | Maximum gross total (inclusive) | |
| min_total | No | Minimum gross total (inclusive) | |
| client_name | No | Filter by client name (partial match) | |
| include_positions | No | When true, include line items in each invoice. Significantly increases response size — only use when needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden; it does disclose the response envelope and that items are slim by default, which is genuinely useful. However, it labels pagination 'cursor-style' while the schema exposes page/per_page, a mild mismatch, and it never states the read-only nature or how large result sets behave.
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 tight sentences, front-loaded with purpose and return shape, with the cost-related caveat last. Nothing is wasted.
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 14-parameter, no-output-schema search tool, the description usefully sketches the return shape and the payload-size tradeoff. It lacks only sibling disambiguation and read-only confirmation, both of which matter given no annotations.
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 parameters are already documented in detail. The description only adds framing around include_positions (slim-by-default items), which the schema itself also warns about; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (invoices) plus the defining capability (rich filtering, pagination). It does not distinguish itself from close siblings such as get_invoice, invoices_summary, or search_supplier_invoices, which an agent must resolve on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'search' and there is one conditional hint (set include_positions when line items are needed), but the description never says when to pick this over invoices_summary or a report tool. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for delivery notices (avize de expediție).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| client_name | No | Filter by client name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Search' implies a read-only, non-destructive lookup, but the description says nothing about result ordering, pagination behavior, whether an empty result set is normal, or what a returned notice contains. Schema fields hint at paging and filtering, but behavioral traits are undisclosed.
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 front-loaded sentence with zero filler and no repetition of schema detail. It is efficient, though its brevity reflects under-specification rather than disciplined editing.
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 7-parameter list tool with no annotations and no output schema, the description should at minimum characterize the returned objects and note that results are paginated and filterable. The Romanian term helps domain recognition but does not fill the gaps an agent needs to invoke and interpret the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself explains state aliases ('issued' = open+closed), date formats (YYYY-MM-DD), partial matching on client_name, and per_page limits. The description adds nothing beyond this, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and a distinct resource ('delivery notices / avize de expediție'), which separates it from the many search_invoices/search_orders/search_supplier_* siblings by domain object. It does not, however, clarify the relationship to adjacent document tools like get_supplier_document or explain that it returns a paginated list rather than a single notice.
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?
There is no guidance on when to use this tool versus alternatives — nothing says whether delivery notices are a subset of invoices, how they relate to supplier documents, or what conditions select this over get_document_pdf. The agent must infer usage entirely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for orders (comenzi).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| client_name | No | Filter by client name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It implies a read-only search but does not disclose result format, default sorting, pagination behavior beyond the schema fields, or permissions.
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 front-loaded sentence with no wasted words. However, it is under-specified rather than optimally concise for a tool with seven optional filters and many siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should explain more about return values, pagination, and default behavior. It leaves an agent with only the schema-documented filters and no broader context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so all seven parameters are well documented. The description adds no additional parameter meaning beyond what the schema already provides, making the baseline 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 states a specific verb and resource: search for orders, with the Romanian alias 'comenzi'. It is clear what the tool does, but it does not distinguish it from the many sibling search tools, especially search_supplier_orders.
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 no guidance on when to use this tool versus alternatives such as search_supplier_orders or search_invoices. It also gives no exclusions, prerequisites, or context for the optional filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search payments linked to invoices, proforma invoices, orders, or supplier invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| date_to | No | Filter payment date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| order_id | No | Filter by order ID | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter payment date >= this date (YYYY-MM-DD) | |
| invoice_id | No | Filter by invoice ID | |
| payment_type | No | Filter by payment method, e.g. "cash", "bank" | |
| proforma_invoice_id | No | Filter by proforma invoice ID | |
| supplier_invoice_id | No | Filter by supplier invoice (supplier document) ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Search' implies a read, but the description says nothing about result shape, pagination behavior, filter combination logic (AND vs OR), or what happens with no filters — all important for a 10-parameter query tool.
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 front-loaded sentence with no filler, which is structurally clean. It is arguably too terse for a 10-parameter tool, but there is no wasted language to cut.
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 10 optional parameters, no annotations, and no output schema, the description should explain filtering semantics (are criteria combined?), empty-filter default behavior, and roughly what is returned. None of this is present, leaving significant gaps for an agent to guess at.
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 every parameter is already documented with type and meaning (dates in YYYY-MM-DD, per_page max 100, etc.). The description only restates the document-linkage theme that the id parameters already convey, adding no syntax or format detail 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?
States a specific verb and resource ('search payments') plus the document types payments can be linked to, which lets an agent distinguish it from sibling searches like search_invoices or search_receipts. It does not explicitly contrast with search_receipts or report_payments_vs_invoiced, so it falls just short of full sibling 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?
There is no guidance on when to use this versus alternatives such as search_receipts, report_payments_vs_invoiced, or the individual search_* document tools. The only implied usage is the topic overlap with the name; nothing states preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for products / services defined in the account.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Product code | |
| name | No | Product name / description (partial match) | |
| limit | No | Maximum results (default 20) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| stock_tracked | No | Only products whose stock is (true) / is not (false) tracked | |
| below_min_stock | No | Only stock-tracked products at or below their minimum stock level ("what is running low?") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden and it does not: it never says read-only, never mentions the default 20-result cap, result ordering, or whether matching is case-sensitive. 'Defined in the account' hints at tenant scoping but is the only extra information given.
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 front-loaded sentence with no filler. It is efficient, though its brevity is partly under-specification rather than disciplined compression.
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 six optional parameters, no annotations and no output schema, the agent needs to know what a result record looks like, how limit/pagination behaves, and that omitting filters is legal and may return a truncated list. None of that is present.
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 every parameter has a description, including the useful semantic gloss on below_min_stock ("what is running low?"). The tool description itself adds nothing about parameters, so the schema-baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('products / services defined in the account'), which clearly separates it from the many create_*/update_*/delete_* siblings and the other search_* tools. It stops short of explicitly naming alternatives, but the resource is 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?
No guidance on when to use this versus count_records or the create/update/delete product tools, and no note that all filters are optional (an unfiltered call returns everything up to the limit). The only usage signal is the implicit word 'Search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for proforma invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| series | No | Filter by proforma invoice series | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| client_name | No | Filter by client name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses nothing: not that the call is read-only, not the result shape, not pagination limits beyond what the schema happens to say, not ordering. For an eight-parameter list tool with zero annotation coverage this is a complete gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One well-formed, front-loaded sentence with no padding or filler, so nothing needs trimming. It is, however, too thin to be considered appropriately sized for an eight-parameter search tool, so it earns only the middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and eight parameters, the description would need to cover return shape and pagination behavior; it covers neither. The only saving grace is that the operation is an obvious low-risk read implied by the name, keeping this from a 1.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself is unusually informative (the "issued" alias semantics, comma-separated state values, partial-match on client_name, per_page max). The description adds nothing beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description "Search for proforma invoices" is a near-verbatim restatement of the tool name, adding only the word "for". It gives no indication of what distinguishes it from search_invoices, search_supplier_proforma_invoices, or get_invoice, so the sibling differentiation burden falls entirely on the name.
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?
There is no when-to-use guidance, no exclusions, and no named alternative. An agent must infer from the names alone that this is the customer-side proforma search while search_supplier_proforma_invoices covers supplier documents, and nothing states whether pagination or a filter is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for receipts (chitanțe).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| client_name | No | Filter by client name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, yet it says nothing beyond the name. Read-only intent is only implied by the verb "search", and there is no mention of result ordering, default page size behavior, or what a result contains.
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 single short sentence is front-loaded and wastes no words, but its brevity is under-specification rather than concision — it omits information an agent needs, and the parenthetical translation is the only added content.
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?
A seven-parameter search tool with no annotations and no output schema, competing with roughly twenty sibling search tools, needs more than one sentence. The fully documented schema saves it from a 1, but an agent still lacks any behavioral or routing 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?
All seven parameters have full schema descriptions (states, date ranges, currency, partial-match client name, pagination), so the schema already does the semantic work. The description adds nothing to it, making baseline 3 correct.
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?
"Search for receipts (chitanțe)" essentially restates the tool name, adding only a Romanian synonym. It gives no scope (which receipt fields are searchable, whether results span drafts, whether it searches across suppliers) and nothing that distinguishes it from the many sibling search_* 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?
There is no guidance on when to use this instead of search_invoices, search_supplier_fiscal_receipts, count_records, or get_invoice. No mention of prerequisites, pagination strategy, or which use-cases select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search simplified supplier invoices (facturi simplificate de la furnizor).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| supplier_name | No | Filter by supplier name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing beyond the resource name. It does not state that this is a read-only listing, what a page of results looks like, whether drafts are included by default, or any permission/rate constraints; only the schema's parameter text hints at pagination and state semantics.
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 short sentence, front-loaded with the verb and resource, with the bilingual gloss in parentheses for domain disambiguation. Nothing is wasted, but the brevity borders on under-specification rather than tightness.
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 seven-parameter search tool with no annotations and no output schema, the description omits everything an agent would want: result shape, ordering, default state filter, and how it differs from the sibling supplier-invoice searches. The schema covers parameters well, but the description contributes nothing to overall completeness.
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% — all seven parameters are documented in the schema, including the non-obvious 'issued' alias and comma-separated state syntax. The description adds no parameter meaning of its own, 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 names a specific verb ('Search') and a specific resource ('simplified supplier invoices'), with the Romanian term added for domain precision. It is clear what the tool returns at a high level, but it never distinguishes itself from the near-identical sibling search_supplier_invoices, leaving the agent to infer the difference.
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?
There is no guidance on when to use this versus search_supplier_invoices, get_supplier_document, or create_simplified_supplier_invoice, and no mention of when it should not be used. Usage is only implied by the verb 'Search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search supplier fiscal receipts (bon fiscal furnizor).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| supplier_name | No | Filter by supplier name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about permissions, result ordering, or what a returned receipt record contains. The only behavior hinted at is that it is a search (read) operation, derived from the verb.
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 short sentence, front-loaded and free of waste, but its brevity comes at the cost of under-specification rather than genuine efficiency.
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?
Seven filters, no annotations, and no output schema; an agent still cannot tell what a result record looks like or how results are ordered. The description should do more to compensate for the missing structured metadata.
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%, with each of the seven optional filters documented in the schema, including the non-obvious "issued" state alias and the comma-separated convention. The description adds no parameter meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (search) and resource (supplier fiscal receipts), reinforced by the Romanian domain term "bon fiscal furnizor," which disambiguates the document type. It does not, however, distinguish this from adjacent siblings like search_supplier_invoices or get_supplier_document.
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?
No indication of when to prefer this tool over the many sibling search_* tools or over get_supplier_document. The agent must infer usage purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search supplier invoices (purchase invoices).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| supplier_name | No | Filter by supplier name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but says nothing about read-only safety, permission requirements, pagination behavior, or result shape. Only the weak implication of "search" suggests a read operation, which is a thin basis for a mutation-free 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?
A single front-loaded sentence with a useful disambiguating parenthetical and zero filler. It is efficient, though the brevity is achieved by omitting rather than by tight construction.
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 7-parameter, all-optional search tool in a dense family of near-identically named siblings with no annotations and no output schema, the definition should clarify which document family it covers and what a result contains. The one-line description leaves that entirely to inference.
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% — every parameter including the state alias semantics and date formats is documented in the schema. The description adds nothing beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource ("search supplier invoices") with a clarifying gloss "(purchase invoices)" that disambiguates from sales invoices. However, it does not name the closely related siblings (search_invoices, search_simplified_supplier_invoices, search_supplier_orders), leaving the agent to infer the boundary.
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?
No guidance on when to use this versus search_invoices (sales side) or the simplified/fiscal-receipt supplier variants, and no prerequisites stated. Usage is only implied by the word "search".
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search supplier orders (purchase orders).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| supplier_name | No | Filter by supplier name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. "Search" implies a read-only query, but the description does not state permissions, result behavior, pagination behavior, or whether results include drafts; it adds essentially no behavioral context beyond the name.
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 short sentence with no wasted words, front-loading the verb and resource. It is appropriately sized for a concise tool description, even though more substance would be needed elsewhere.
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 seven-parameter search tool with no output schema and no annotations, the description is minimal but the schema covers all filters. It does not explain return shape or differentiate from search_orders, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema fully documents all seven optional parameters, including state filtering and date ranges. The description adds no parameter meaning beyond the schema, so the baseline 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?
States a specific verb and resource: "Search supplier orders," with the clarifying parenthetical "(purchase orders)." It is clear what the tool does, but it does not differentiate itself from the sibling search_orders tool or explain how supplier orders differ from regular orders.
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 no explicit guidance on when to use this tool versus search_orders or other supplier-document search tools. Usage is only implied by the name, with no exclusions or alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search supplier proforma invoices (purchase proformas).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, 1-based (default 1) | |
| state | No | Filter by document state: draft, open, closed, cancelled. The alias "issued" means open+closed (finalised — not a draft, not cancelled). Comma-separated for several (e.g. "open,closed"). Omit for all states. | |
| date_to | No | Filter document date <= this date (YYYY-MM-DD) | |
| currency | No | Filter by currency code, e.g. "RON", "EUR" | |
| per_page | No | Results per page (default 20, max 100) | |
| date_from | No | Filter document date >= this date (YYYY-MM-DD) | |
| supplier_name | No | Filter by supplier name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden and it says nothing about read-only semantics (only implied by 'search'), default result ordering, whether a total count is returned, or pagination behavior. The keyword 'search' is the only behavioral signal an agent gets.
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 front-loaded sentence with zero filler. It is efficient, though there is so little content that structure is barely a factor.
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 tool has seven optional filters, no annotations, and no output schema, so the description has to do more than name the resource. It never explains what a supplier/purchase proforma materially is for the user, what the default (omitting 'state') returns, or what a result record contains, leaving an agent to infer everything from the name.
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% — all seven filter parameters, including the non-obvious 'issued' state alias and the YYYY-MM-DD date format, are documented in the schema itself. The description adds nothing about filtering semantics, which is acceptable at the baseline but leaves no added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('Search supplier proforma invoices') and adds the clarifying gloss '(purchase proformas)', which separates it from the sibling search_proforma_invoices (presumably own/sales proformas) in a way the name alone does not. It does not name or exclude any sibling explicitly, so it stops short of a 5.
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?
There is no statement of when to use this versus search_proforma_invoices, search_supplier_invoices, or get_supplier_document, and no prerequisites or exclusions. The only hint at usage is the verb 'search' itself, which is the minimum implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for suppliers by id, name, email, uid (VAT/CUI), or telephone. Results are returned newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Supplier ID — returns that exact supplier | |
| uid | No | Supplier fiscal code / CUI / VAT number | |
| name | No | Supplier name (partial match) | |
| No | Supplier email address | ||
| limit | No | Maximum results, newest first (default 20) | |
| telephone | No | Supplier phone number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that results are returned newest first and that searching is by supplier attributes, which implies a read-only operation. It does not state what happens when no filters are supplied, whether results are paginated beyond limit, or what supplier fields are returned.
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 compact sentences and front-loads the search fields. The ordering detail is useful but partly redundant with the schema's limit description, so it is not perfectly waste-free.
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 six-parameter search tool with no annotations and no output schema, the description covers the core search dimensions and ordering. It leaves important gaps around empty-filter behavior and result shape, so 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?
Schema description coverage is 100%, so the schema already documents all six parameters, including partial matching for name and the limit default. The description adds little beyond restating the same searchable fields and expanding uid to VAT/CUI, so the baseline 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 states a specific verb and resource: search suppliers. It also lists the searchable fields, so an agent can distinguish this from create_supplier or update_supplier. It stops short of explicitly differentiating from sibling search tools such as search_clients, but the supplier resource is 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?
Usage is implied by the resource name: use this when looking up suppliers. However, the description gives no explicit when-to-use guidance versus alternatives such as update_supplier, search_clients, or get_supplier_document, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a document (invoice, proforma invoice, etc.) by email.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | CC email address (optional) | |
| to | Yes | Recipient email address | |
| bcc | No | BCC email address (optional) | |
| body | Yes | Email body text | |
| document_id | Yes | Document ID (invoice, proforma, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does not meet it. For an irreversible outbound-email action, it says nothing about side effects (does it mark the document as sent, does it generate and attach a PDF, is the email sent immediately, can it be undone), nor about permissions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with zero waste. It is efficient, but the brevity comes at the cost of the behavioral detail an email-sending tool needs.
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 five parameters, no annotations, and no output schema, the agent gets no information about what happens on success (confirmation object? message id?), what the email looks like (template vs. raw body, attachment generation), or failure modes such as invalid document_id. Substantially incomplete for a mutation with external side effects.
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 every parameter (to, cc, bcc, body, document_id) is already documented in the schema. The description adds only that any document type is valid for document_id, which is marginal added value; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Send') and resource ('a document') plus the channel ('by email') and gives concrete examples (invoice, proforma invoice). It is the only send/email tool among a large set of create/search/update/delete siblings, so it is inherently distinguishable, though the description never says so explicitly.
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?
There is no guidance on when to use this versus alternatives, no prerequisites (must the document already exist / be issued / be finalized before sending?), and no mention of whether the send is immediate or queued. The agent must infer all of this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit an invoice to the ANAF SPV portal (e-Factura UBL) using the e-Factura properties already stored on the invoice (invoice_type_code, vat_type, payment_method, document_position_units). Returns the resulting EfacturaTransaction JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID to submit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that e-Factura properties are read from the stored invoice rather than supplied as parameters, and that a transaction JSON is returned, but it says nothing about ANAF credentials/authorization, whether a submission is irreversible, how failures or rejections surface, or whether the call is async and requires status polling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and target system, then the data source and return value. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The return value is named (EfacturaTransaction JSON) even without an output schema, which is helpful. However, for a write operation against an external government portal with no annotations and no output schema, the description leaves out auth requirements, failure modes, and any follow-up flow (status refresh), so it is only 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?
Only one parameter exists and the schema documents it at 100% coverage, which sets the baseline at 3. The description adds modest value by explaining that invoice_id selects an invoice whose stored e-Factura properties drive the submission, but adds no format or constraint details 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?
States a specific verb and resource: submits an invoice to the ANAF SPV portal via e-Factura UBL. It is clearly distinguishable from siblings like export_efactura_xml, get_efactura_status, and refresh_efactura_status, which read or export rather than submit.
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 name and description imply submission is for actually filing with ANAF, but there is no explicit statement of when to prefer this over export_efactura_xml or how it relates to get_efactura_status/refresh_efactura_status afterward. Usage is inferable from context rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing client by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Client ID (from search_clients) | |
| uid | No | Fiscal code / CUI / VAT number | |
| city | No | City | |
| name | No | Full name or company name | |
| No | Email address | ||
| address | No | Street address | |
| country | No | Country code | |
| telephone | No | Phone number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, and it omits the single most important behavior for an 8-parameter update tool: whether omitted fields are preserved (partial patch) or cleared (full replace). It also says nothing about permission requirements, whether updates are reversible, or what happens when the ID is unknown.
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 short sentence with zero waste, front-loading the verb and resource immediately. It is efficiently written, though the terseness is part of the under-specification problem rather than a virtue at this tool's complexity.
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 mutation tool with eight parameters, no annotations, and no output schema, the description should say what a successful update returns and how partial payloads are handled. Neither is present, leaving critical invocation semantics undefined.
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 every field including the id ("from search_clients") is already documented, which sets the baseline at 3. The description adds nothing beyond "by ID" — no guidance on which of the seven optional fields matter or on update semantics for omitted ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Update an existing client by ID"), which cleanly separates it from create_client, delete_client, and search_clients in the sibling set. It stops short of naming which client attributes can be modified, but the action and target are 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?
"Existing" weakly implies the client must already exist, but there is no statement of when to reach for this tool over create_client, no prerequisite (e.g. obtain the ID via search_clients), and no exclusion criteria. The agent is left to infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice ID (from search_invoices) | |
| currency | No | Currency code | |
| due_date | No | Due date in YYYY-MM-DD format | |
| due_days | No | Days until payment is due | |
| client_id | No | New client ID | |
| document_date | No | Invoice date in YYYY-MM-DD format | |
| lower_annotation | No | Text below line items | |
| upper_annotation | No | Text above line items | |
| document_positions | No | Replacement line items. By default these replace ALL existing positions; set document_positions_update_policy: "append" to add instead. | |
| document_positions_update_policy | No | How document_positions are applied: "replace" (default — swap all existing lines) or "append" (add to existing lines). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and provides none of it: it does not say whether omitted fields are left untouched or cleared, does not warn that document_positions replaces ALL existing line items by default (a destructive side effect only documented inside the schema), and does not mention permissions, reversibility, or recalculation of totals. A mutation tool with zero annotation coverage needs far more.
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 front-loaded sentence with zero filler. It is efficient, though the brevity reflects under-specification rather than disciplined editing.
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?
This is a 10-parameter mutation tool with no annotations and no output schema, meaning the description is the only place behavioral guarantees could appear, and it says nothing. Critical facts such as default replacement of all line items, partial-update semantics, and validation behavior are absent from the description text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema itself documents all ten parameters in detail, including the replace-vs-append policy, so the baseline is 3. The description only restates the id parameter ('by ID') and adds no semantics of its own.
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?
Names a specific verb and resource (update an invoice) and adds the lookup key (by ID), which distinguishes it from the many create_*/delete_* siblings in the namespace. There is no other update_invoice tool, so no sibling disambiguation is needed, but the description says nothing about what aspects of the invoice are updatable.
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?
No guidance on when to use this versus create_invoice, get_invoice, or the specialized update_* siblings. It also omits the prerequisite that the ID must come from search_invoices, a hint that only appears buried in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing payment by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Payment ID (from search_payments) | |
| amount | No | Payment amount | |
| currency | No | Currency code | |
| description | No | Notes / description | |
| payment_date | No | Payment date in YYYY-MM-DD format | |
| payment_type | No | Payment method |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and offers essentially none: it does not say whether this is a partial or full replacement update, what happens to omitted fields, whether the payment record is mutable after issuance, or what permissions are required. 'Update' alone discloses nothing beyond the mutation implied by the name.
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 short, front-loaded sentence with no filler. It is efficient, though that efficiency comes partly from omitting content the agent needs.
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?
This is a six-parameter mutation tool with no annotations and no output schema, yet the description covers only the ID-based targeting. The partial-vs-full update semantics and post-call state are entirely undocumented, which is a real gap for a destructive-capable 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?
Schema description coverage is 100%, so every parameter including the ID's provenance from search_payments and the YYYY-MM-DD date format is already documented. The description adds no parameter-level meaning beyond the schema, which is the baseline 3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Update') and resource ('an existing payment by ID'), so the action is immediately clear. However, it does nothing to separate it from the surrounding create_payment / delete_payment / search_payments family, which the agent must infer from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to update versus create or delete a payment, nor any prerequisite such as needing a payment ID obtained from search_payments (that hint lives only in the schema). The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing product by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Product ID (from search_products) | |
| vat | No | VAT percentage | |
| code | No | Product code | |
| unit | No | Unit of measure | |
| price | No | Unit price excluding VAT | |
| barcode | No | Barcode | |
| currency | No | Currency code | |
| quantity | No | Default quantity when adding the product to a document | |
| description | No | Product name / description | |
| product_kind | No | goods, service or consumable; a service cannot be stock-tracked | |
| stock_tracked | No | Track this product's stock (stock management module) | |
| min_stock_level | No | Minimum stock level; at or below it the product counts as low on stock | |
| default_stock_warehouse_id | No | Warehouse a document line books against when none is given (from list_stock_warehouses) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and says nothing beyond "update". It does not disclose whether this is a partial or full replacement update, what happens to the 12 optional fields when omitted, whether changes are reversible, or what validation/errors to expect — critical for a 13-parameter mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste and no hedging. It is efficient, though the terseness is partly under-specification rather than disciplined brevity.
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 13-parameter mutation with no annotations and no output schema, the description is far too thin. The agent cannot tell whether omitted fields are preserved or nulled, whether stock fields are validated against the stock module, or what a successful response returns.
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 every parameter including enum-like semantics (product_kind, stock_tracked, min_stock_level) is already documented in the schema. The description adds nothing parameter-specific, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Update an existing product by ID") and names the addressing key, so intent is unambiguous. It does not differentiate against siblings such as create_product, delete_product, or search_products, but the verb alone carries that weight reasonably well.
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?
No statement of when to use this versus create_product or delete_product, and no prerequisites such as required permissions or required prior state (e.g., the product must already exist). The only routing hint is buried in the schema ('from search_products'), not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing supplier by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Supplier ID (from search_suppliers) | |
| uid | No | Fiscal code / CUI / VAT number | |
| city | No | City | |
| name | No | Supplier name | |
| No | Email address | ||
| address | No | Street address | |
| country | No | Country code | |
| telephone | No | Phone number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses almost nothing: it does not say whether this is a partial or full replacement update (only id is required, which hints partial), what happens to omitted fields, whether the ID must already exist, or what errors result from an invalid ID. For a mutation tool this is a significant gap.
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 front-loaded sentence with no filler. It is efficient, though arguably under-specified rather than genuinely concise in a way that helps invocation.
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 an eight-parameter mutation tool with no annotations and no output schema, the description is too thin: it omits update semantics (partial vs full), permission or existence requirements, and the effect of the call. The schema covers parameters, but behavior is left unexplained.
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 all eight parameters are already documented, including the id's provenance from search_suppliers. The description adds nothing beyond "by ID," so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Update an existing supplier") and the identifier mode ("by ID"), which is clear enough on its own. It does not, however, distinguish this from sibling mutations like update_client or update_product, nor from create_supplier/delete_supplier.
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?
There is no guidance on when to use this versus search_suppliers (to find the ID) or create_supplier (for new records), and no prerequisites or exclusions are stated. The agent must infer the workflow entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
count_recordscreate_clientcreate_invoicecreate_ordercreate_paymentcreate_productcreate_proforma_invoicecreate_receiptcreate_simplified_supplier_invoicecreate_suppliercreate_supplier_fiscal_receiptcreate_supplier_invoicecreate_supplier_ordercreate_supplier_proforma_invoicedelete_clientdelete_invoicedelete_orderdelete_paymentdelete_productdelete_proforma_invoicedelete_receiptdelete_simplified_supplier_invoicedelete_supplierdelete_supplier_fiscal_receiptdelete_supplier_invoicedelete_supplier_orderdelete_supplier_proforma_invoiceexport_efactura_xmlget_document_pdfget_efactura_statusget_invoiceget_supplier_documentinvoices_summarylist_efactura_receivedlist_seriesrefresh_efactura_statusreport_invoiced_by_periodreport_outstanding_balancesreport_payments_vs_invoicedreport_top_clientsreport_vat_collectedreport_vat_deductiblesearch_clientssearch_invoicessearch_noticessearch_orderssearch_paymentssearch_productssearch_proforma_invoicessearch_receiptssearch_simplified_supplier_invoicessearch_supplier_fiscal_receiptssearch_supplier_invoicessearch_supplier_orderssearch_supplier_proforma_invoicessearch_supplierssend_documentsubmit_invoice_to_efacturaupdate_clientupdate_invoiceupdate_paymentupdate_productupdate_supplier
Add one secure layer between your agents and this server.