Read KiotViet products, customers, invoices, orders and stock; create customers and orders.
Scored across 29 tools
Tools map cleanly to resource+operation pairs (list/get/create) with distinct resources: customers, products, orders, invoices, purchase orders, returns, suppliers, price books, cashflow, stock. The main friction is the parallel id-vs-code variants (get_order vs get_order_by_code, get_invoice vs get_invoice_by_code) and the cluster of transaction types (orders, invoices, purchase orders, supplier orders, returns), but descriptions clarify each clearly.
Every tool follows a single predictable pattern: kiotviet_ prefix + verb_noun in snake_case (list_products, get_product, get_product_by_code, create_customer). Even the _by_code variants extend the pattern consistently with no camelCase or verb-style mixing.
29 tools is at the heavy end, and the breadth is driven by many distinct entities (branches, categories, customers, products, price books, orders, invoices, stock, cashflow, purchase orders, supplier orders, suppliers, returns, users) which justifies much of it. However the read-heavy surface with repeated list/get/get_by_code triples per entity inflates the count somewhat.
Read coverage is broad, but only two write operations exist (create_customer, create_order), and create_order explicitly does not produce an invoice or record payment. There are no update/delete tools, no product or supplier creation, no invoice creation or payment recording, and no return/purchase-order creation, leaving significant lifecycle gaps for real workflows.
WRITE: create a new customer in the shop (name required; code is generated by KiotViet if omitted). Always check with the user first, and look the customer up by phone before creating a duplicate. POST /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Customer code (optional; KiotViet generates one). | |
| name | Yes | Customer name. | |
| No | Email address. | ||
| address | No | Street address. | |
| comments | No | Note on the customer. | |
| tax_code | No | Tax code (ma so thue). | |
| group_ids | No | Customer group ids. | |
| birth_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). | |
| organization | No | Company name. | |
| contact_number | No | Phone number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-idempotent, open-world write. The description adds genuinely useful context beyond that: code is auto-generated when omitted, duplicates are the primary risk (hence the pre-lookup), and user confirmation is required before the write. It doesn't describe the response payload, but the safety and dedupe behavior is well covered.
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 'WRITE:' severity marker and the required-parameter fact, then the operational guidance, then the endpoint. Every clause carries information; 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?
For a 10-parameter mutation with no output schema, the definition covers the operation, the required field, auto-generation behavior, and the confirmation/dedupe workflow. The one meaningful gap is what comes back from a successful create (customer id or code) so the agent can chain a follow-up call. Otherwise it 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%, so all 10 parameters are already documented in the schema. The description only reinforces two of them (name required, code auto-generated), which is helpful emphasis but adds no syntax, format, or constraint detail the schema doesn't already carry. The 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 opens with an explicit 'WRITE:' marker and states the specific verb and resource: create a new customer in the shop. That verb+resource pairing is easily separable from the get_/list_ siblings that share the customer domain. Nothing here restates the tool name tautologically.
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 concrete preconditions: confirm with the user first, and look up by phone before creating a duplicate. That establishes when-and-how to call it, including a de-duplication workflow. It stops short of naming the specific alternative tool (kiotviet_get_customer_by_code), so the agent must infer which sibling to use for the lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a sales order (an order, not an invoice: no invoice is made and no payment is recorded) with lines of existing products in a branch, for an existing customer or none. Always confirm the products, quantities and prices with the user first. POST /orders.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | The order lines. | |
| discount | No | Order discount amount. | |
| branch_id | Yes | Branch the order is for (see kiotviet_list_branches). | |
| sold_by_id | No | Salesperson user id (see kiotviet_list_users). | |
| customer_id | No | Existing customer id (see kiotviet_list_customers). | |
| description | No | Note on the order. | |
| sale_channel_id | No | Sales channel id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true. The description adds real value beyond that: the write does not generate an invoice and does not record payment, and inputs must already exist. It omits the practical consequence of non-idempotency (retries can create duplicate orders), which would be the final missing piece.
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 compact sentences, front-loaded with the 'WRITE:' marker and the order-vs-invoice disambiguation before the operational caveats. No restatement of the title, 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?
For a 7-parameter mutation tool with no output schema, the description covers what is created and the preconditions, but never states what comes back (e.g., the new order id), which the agent needs in order to chain into kiotviet_get_order. That is the one substantive omission.
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 genuine semantics: items must reference existing products, branch_id is the branch the order belongs to, and customer_id is optional ('existing customer or none'). That resolves the optionality question an agent would otherwise have to infer from the required list.
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 sales order) and immediately disambiguates from the nearest confusing concept: 'an order, not an invoice: no invoice is made and no payment is recorded'. The scope is further narrowed to lines of existing products in a branch and an existing customer or none, so an agent can distinguish this from any invoice-related sibling without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete pre-call workflow constraint ('Always confirm the products, quantities and prices with the user first') and implies prerequisite resources exist (products, branch, customer). It does not name an explicit alternative tool for the invoice path, but with no create_invoice sibling available, the when-to-use context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product category by id (name, parent, children). GET /categories/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | Yes | KiotViet category id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld and non-destructive, so the safety profile is covered. The description adds real value by disclosing the endpoint (GET /categories/{id}) and the shape of the returned record (name, parent, children), though with no output schema, error/not-found behavior and whether children are full sub-trees or ids remain 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?
Two short fragments, zero waste, with the core identity of the tool front-loaded before the endpoint detail. Nothing could be removed without losing 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 read tool whose annotations carry the safety profile, this is nearly complete: it says what is fetched and what fields come back. Minor gaps are the absence of any not-found/error note, which matters for an open-world API read.
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 a single parameter and schema description coverage is 100% ('KiotViet category id.' with positive-integer bounds). The description's 'by id' restates rather than extends the schema, so the baseline 3 applies — no format, sourcing, or lookup guidance 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-resource pair ('One product category by id') and scopes it to a single record, which separates it from the sibling kiotviet_list_categories without naming it. The parenthetical return fields add precision about what a category record contains.
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 only implied by 'by id' — an agent can infer this is the single-record lookup versus the list tool, but nothing states prerequisites, when to prefer it over the list variant, or what to do if the id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer by id: contact data, debt, total invoiced, reward points, groups. GET /customers/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | KiotViet customer id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description contributes the useful detail that the response spans contact data, debt, invoiced totals, reward points and groups. It says nothing about not-found handling or error behavior for a live external API.
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 compact fragments front-load the resource scope and then the endpoint. Every element earns its place: the field list is informative and the endpoint gives an integration anchor, with 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?
For a single-parameter read tool with full schema coverage and annotations, this is largely sufficient, and the field enumeration compensates for the absence of an output schema. The only meaningful gap is undefined behavior when the customer id does not exist.
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 'KiotViet customer id' with a positive-integer constraint. The description's 'by id' merely restates that framing; it adds no format or sourcing guidance 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 (fetch one customer) and the scoping key ('by id'), which implicitly separates it from kiotviet_get_customer_by_code and kiotviet_list_customers. It also enumerates the payload categories returned. It stops short of explicitly naming the sibling tools it is not.
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 rather than stated: an agent can infer this is the lookup path when a numeric id is available, and the 'by id' phrasing hints at the code-based alternative. There is no explicit when-to-use / when-not-to-use rule and no mention of what to do if the id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer by customer code. GET /customers/code/{code}.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | KiotViet customer code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint path 'GET /customers/code/{code}', which merely restates the read-only nature and says nothing about behavior when the code is not found or what the single-object response looks like.
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?
Extremely short and front-loaded with the purpose. The second sentence repeating the HTTP route is low-value padding, but nothing else 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 simple one-parameter read whose annotations cover the safety profile, this is minimally sufficient. It nonetheless leaves the agent without the not-found behavior or any hint of the returned object, which matters because there is no 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?
Single parameter with 100% schema description coverage ('KiotViet customer code.'), so the schema carries the burden and the baseline is 3. The description confirms the lookup is by code but adds no format, casing, or uniqueness 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?
It identifies the resource (customer) and the lookup key (customer code), which implicitly distinguishes it from kiotviet_get_customer. But 'One customer by customer code' is a terse fragment with no verb, and it never names the sibling it replaces, so the agent must infer the distinction from the sibling's name 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 statement of when to use this versus kiotviet_get_customer, kiotviet_list_customers, or the other *_by_code siblings. The agent gets no condition, no prerequisite, and no exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One invoice by id with its lines, payments and delivery. GET /invoices/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | KiotViet invoice id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine value by disclosing that the response is a composite object including line items, payments and delivery, which matters for a single-fetch 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?
Two short sentences with the payload description front-loaded and no filler. The trailing endpoint reference is mildly redundant but inexpensive and aids orientation.
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 full annotation coverage and no output schema, the description covers enough: identity, what comes back, and the backing endpoint. The only meaningful gap is not routing the agent between id-based and code-based lookups.
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 there is only one parameter (invoice_id, described as 'KiotViet invoice id'), so the schema does the work. The description's 'by id' adds nothing beyond it — no format, validity, or not-found behavior.
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: retrieve a single invoice by id, and names the payload it returns (lines, payments, delivery). This clearly distinguishes it from kiotviet_list_invoices, though it never explicitly distinguishes it from the sibling kiotviet_get_invoice_by_code.
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 only implied by 'by id' — the agent can infer this is the id-based lookup, but the description never says when to prefer it over kiotviet_get_invoice_by_code or list_invoices. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One invoice by invoice code (for example HD000123). GET /invoices/code/{code}.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | KiotViet invoice code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /invoices/code/{code}) and a code format example, but says nothing about error behavior when a code is not found or what the payload looks like.
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 terse sentences with the resource and identifier pattern front-loaded and no padding. The telegraphic style omits a leading verb phrase, but 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 one-parameter read with annotations covering safety and no output schema, the description is minimally sufficient. It leaves the agent without any hint about the returned invoice shape or not-found handling, which is a gap for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'code' parameter is already documented as the KiotViet invoice code. The description's example format (HD000123) is a small but useful addition; per the baseline rule for full coverage this stays at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('one invoice by invoice code') and names the identifier type, which implicitly distinguishes it from kiotviet_get_invoice (id lookup) and kiotviet_list_invoices. It never explicitly names those siblings, so differentiation 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?
Usage is only implied by the 'by code' qualifier — an agent can infer this is the lookup to use when it holds an invoice code rather than an id. There is no explicit when-to-use, when-not, or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One sales order by id with its lines, payments and delivery. GET /orders/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | KiotViet order id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the underlying endpoint GET /orders/{id} and enumerates the response sections, but says nothing about error behavior for an unknown id or any auth/rate-limit 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?
Two short sentences with zero filler; the payload description comes first and the endpoint reference is a compact addendum. Nothing could be removed without losing 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 read tool with full schema coverage and read-only annotations, the description covers what is returned and how it maps to the API. The remaining gap is sibling differentiation against kiotviet_get_order_by_code, which matters given the crowded lookalike toolset.
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 order_id parameter ('KiotViet order id.', integer > 0), so the schema carries the semantics. The description only restates 'by id' and adds no format, sourcing, or lookup hint beyond that.
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 and resource ('One sales order by id') plus the returned payload (lines, payments, delivery), which tells an agent exactly what it gets. It does not distinguish itself from the near-identical sibling kiotviet_get_order_by_code, so the by-id vs by-code choice is left implicit.
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 only implied by the phrase 'by id'; there is no explicit statement of when to prefer this over kiotviet_get_order_by_code or kiotviet_list_orders. An agent can infer the case of a known numeric id but must reason about it rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One sales order by order code (for example DH000123). GET /orders/code/{code}.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | KiotViet order code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the REST endpoint, signalling a thin read-only passthrough, but says nothing about not-found behavior, error surfaces, or what fields come 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?
Two short sentences with zero filler, and the identifying detail is front-loaded. The opening is a fragment ('One sales order by order code') that omits an explicit verb, which costs a point but the meaning is never ambiguous.
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 annotations covering safety, this is close to adequate, but with no output schema the description should at least hint at what a returned sales order contains or what happens for an unknown code. As written it is minimal but callable.
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?
With a single required parameter and 100% schema coverage, the baseline is 3, but the description goes one step further by showing the concrete code format (DH000123), which the schema's 'KiotViet order code' text does not supply. That example is genuinely useful for formatting a valid call.
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 the resource (a single sales order) and the lookup key (order code), and reinforces it with a concrete example (DH000123) plus the underlying endpoint GET /orders/code/{code}. This makes it distinguishable from list_orders in practice, but it never explicitly contrasts itself with the sibling kiotviet_get_order, so the code-vs-ID split 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?
Usage is only implied: an agent must infer that this is the tool to use when it holds a human-readable order code rather than an internal ID. There is no explicit when-to-use, when-not-to-use, or statement naming kiotviet_get_order as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The product prices of one price book (product id, code, price), paged. GET /pricebooks/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| price_book_id | Yes | KiotViet price book id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing pagination ('paged') and the shape of the returned records, which matters since no output schema exists.
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 compact fragments with zero filler, the resource and return fields front-loaded before the endpoint. It is a noun phrase rather than a sentence, but nothing could be cut without losing 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?
With no output schema, the description compensates by naming the three returned fields and confirming paged retrieval. Remaining gaps — sort order, behavior on an unknown price_book_id, whether prices reflect overrides — are minor for a simple read getter.
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 every parameter carries its own description, including the paging contract ('Pass the previous reply's next_item'). The description adds nothing parameter-specific, so the baseline 3 holds.
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 resource and scope: the product prices belonging to a single price book, with the returned fields enumerated (product id, code, price). This distinguishes it implicitly from kiotviet_list_price_books, but the sibling is never named, so isolation relies on the reader inferring the plural/singular split.
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 never says when to reach for this over kiotviet_list_price_books or kiotviet_get_product, nor that a price_book_id must come from the list endpoint. The only usage signal is the implicit 'one price book' scoping, which leaves the agent to infer the call sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product by id: code, barcode, name, category, base price, units, attributes, images, stock per branch and price books. GET /products/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | KiotViet product id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new information beyond that: the shape of the returned payload (stock per branch, price books, images), which is valuable given there is no output schema. No auth, rate-limit or not-found behavior is described, 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?
One sentence of substance plus a short endpoint reference, with the identifying constraint ('by id') front-loaded. No filler and nothing that could be cut without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the field enumeration effectively stands in for a return-value description, which is the main completeness risk here. Error/not-found handling is the only meaningful omission, which is a minor 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 description coverage is 100% and the single parameter is fully documented ('KiotViet product id', positive integer). The description only reinforces 'by id' and does not add format or sourcing details, 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?
"One product by id" gives a specific verb+resource and the following clause enumerates the returned fields (code, barcode, name, category, base price, units, attributes, images, stock per branch, price books), which tells an agent exactly what it gets. The 'by id' qualifier implicitly separates it from kiotviet_get_product_by_code and kiotviet_list_products, but neither sibling is named.
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 endpoint notation GET /products/{id} makes the single-record-by-identifier usage clear by implication. However, there is no explicit statement of when to prefer this over kiotviet_get_product_by_code or kiotviet_list_products, and no note about behavior when the id does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product by its product code (SKU). GET /products/code/{code}.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | KiotViet product code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that exactly one product is returned (singular, no pagination) and names the underlying endpoint, but says nothing about behavior when the code does not exist or about auth failures. Modest value on top of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short fragments with zero padding, and the identifying concept (one product by code) comes first. The telegraphic phrasing ('One product by its product code... GET /products/code/{code}.') is terse to the point of being sentence fragments, which costs it a point.
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 lookup with annotations and a fully documented schema, the core need is covered. But there is no output schema, and the description does not describe the returned product shape or the not-found behavior, which is the main remaining gap for an agent.
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 'code' is already documented in the schema with length bounds. The description's '(SKU)' adds a small synonym hint but no format, case-sensitivity, or example 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-less but unambiguous purpose: retrieve one product identified by its product code (SKU). The '(SKU)' gloss clarifies the key type, which implicitly separates it from kiotviet_get_product (by id) and kiotviet_list_products. It never names a sibling explicitly, so differentiation 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?
Usage is only implied: 'by its product code (SKU)' suggests this is the lookup to use when you hold a code rather than an internal id. There is no explicit when-to-use/when-not, no pointer to kiotviet_get_product or kiotviet_list_products as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One goods receipt (nhap hang) by id with its lines. GET /purchaseorders/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| purchase_order_id | Yes | KiotViet goods receipt id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context — that the response includes the line items and the underlying REST path — but says nothing about not-found behavior or required auth, so it is useful but not thorough.
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, zero filler, with the core payload description (id plus lines) front-loaded before the endpoint detail. Every clause carries information an agent can act on.
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 full annotation coverage and no output schema, the description covers what is returned (header plus lines) and how to address the record, which is sufficient to invoke correctly. Missing only an explicit pointer to the list sibling for id discovery.
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 a single required parameter with 100% schema description coverage ("KiotViet goods receipt id."), so the schema already does the work. The description's "by id" adds no syntax, format, or provenance detail beyond that, which is the baseline-3 case for a fully documented one-param 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 (retrieve one), a specific entity (goods order / goods receipt, with the Vietnamese term nhap hang for disambiguation), and scope (by id, with its lines). The singular "one ... by id" implicitly separates it from kiotviet_list_purchase_orders, 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?
Usage is only implied: an agent can infer it should call this when it already has a numeric receipt id and should call kiotviet_list_purchase_orders when it does not. The description never states that precondition or names the alternative, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One customer return by id with its lines. GET /returns/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| return_id | Yes | KiotViet return id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the response includes line items ('with its lines'), with no mention of error behavior for missing ids, paging, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero padding, and the core operation is front-loaded before the endpoint reference. Nothing here could be cut without losing 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 single-record fetch with a 100%-covered single parameter and read-only annotations, most of the burden is already carried elsewhere. The description is minimally sufficient but says little about what a return record contains beyond 'its lines', which matters since 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% and the sole parameter has its own description ('KiotViet return id', positive integer), so semantics are fully carried by the schema. The description adds no format, range, or source hints beyond what the schema already provides, making the 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?
States a specific verb and resource ('One customer return by id with its lines') plus the underlying endpoint, so the agent knows it fetches a single return record rather than a list. The contrast with kiotviet_list_returns is implied by 'by id' but never stated 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 'by id' implies the precondition of already having a return_id, which is the natural selection criterion against kiotviet_list_returns. However, the description never names that alternative or says what to do when only search criteria are available, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One supplier by id. GET /suppliers/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| supplier_id | Yes | KiotViet supplier id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description only adds the underlying REST path (GET /suppliers/{id}); it says nothing about not-found behavior or what 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?
Two short sentences with the cardinality and identifier requirement front-loaded. The REST endpoint line is slightly redundant but informative for API-oriented agents.
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 read tool with full annotation coverage, the description is minimally sufficient. It omits error behavior (e.g., unknown id) and any sense of the returned supplier record, which would help given there is no 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% and the schema itself documents supplier_id as a KiotViet supplier id. The description's 'by id' adds no format or validation detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and cardinality ('one supplier by id'), which lets an agent distinguish it from kiotviet_list_suppliers. The verb is implicit rather than stated, and 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?
No guidance on when to use this versus kiotviet_list_suppliers or kiotviet_get_customer_by_code style lookups. The condition 'when you already have the supplier id' is only inferable from the parameter name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the shop's branches (id, name, code, phone, address). Use the ids to filter other tools. GET /branches.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds the endpoint and enumerates the returned fields, which is modestly useful, but says nothing about pagination behavior or total counts. With annotations carrying the behavioral profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences plus an endpoint reference, with the core purpose front-loaded. Every clause adds either scope, return content, or usage intent, with zero waste.
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 output schema exists, but the description compensates by listing the returned fields, and pagination is fully described in the schema. It is nearly complete; only minor aspects like ordering or total-count behavior are unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the page_size and current_item parameters are documented well in the schema, including the 'pass next_item' convention. The description adds no parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (List) and resource (shop's branches), enumerates the key return fields (id, name, code, phone, address), and includes the underlying endpoint. Combined with the get_* vs list_* sibling naming, an agent can distinguish this from kiotviet_get_* and other list tools 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?
The sentence 'Use the ids to filter other tools' gives a clear motivating context for calling this tool before others. It stops short of naming specific alternatives or when-not conditions, but the usage intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cash-book entries (receipts and payments: code, branch, method, partner, amount, date, status). Filter by branch, direction or date range. GET /cashflow.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Voucher code. | |
| end_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). | |
| page_size | No | Records per page, 1-100 (default 20). | |
| branch_ids | No | Only these branches (see kiotviet_list_branches). | |
| is_receipt | No | true = receipts (money in), false = payments (money out). | |
| start_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| partner_name | No | Customer, supplier or other partner name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful context by naming the GET endpoint and listing the returned cash-book fields. It does not cover authentication, rate limits, or default ordering, but for a read-only list tool this is a reasonably transparent definition.
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 plus the endpoint, with the core purpose front-loaded. It lists returned fields efficiently and adds the filtering capability without filler. Every part earns its place for an agent trying to understand the tool quickly.
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 eight optional parameters, full schema coverage, and rich read-only annotations, the definition is nearly complete. Listing the returned fields compensates for the lack of an output schema. It could still say more about pagination behavior or ordering, but the schema covers the pagination parameter.
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 eight parameters thoroughly. The description groups the filters into branch, direction, and date range, which maps to several parameters but does not add syntax or detail beyond the schema. Baseline 3 is appropriate because the schema carries most of the parameter 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?
The description states a specific verb and resource: list cash-book entries, specifically receipts and payments. It enumerates the main entry fields and endpoint, making the tool's scope clear. It does not explicitly distinguish this from sibling list tools such as invoices or orders, so it falls 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?
It says the entries can be filtered by branch, direction, or date range, which gives implied usage context. However, it does not state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. There is no sibling tool for cash flow specifically, but the guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List product categories (id, name, parent, whether it has children). Set hierarchical to get the category tree. GET /categories.
| Name | Required | Description | Default |
|---|---|---|---|
| order_by | No | Sort field. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| hierarchical | No | Return the nested tree (ignores last_modified_from). | |
| order_direction | No | Sort direction. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint string ('GET /categories') and the field list; it says nothing about pagination limits, default page size implications, or how the flat vs. hierarchical responses differ in shape. Adequate but thin against a read-only 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 short sentences, front-loaded with what the tool returns, followed by the one behavioral knob and the endpoint. Nothing is padded and nothing needs to be re-read.
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 naming the returned fields (id, name, parent, has-children), which is the most important omission to cover. For a zero-required-parameter read-only list tool with fully documented params, this is close to complete; only pagination/total-count expectations are unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the note that hierarchical ignores last_modified_from, so the schema already carries all parameter meaning. The description's only added parameter information is a restatement of the hierarchical flag. 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 gives a specific verb and resource ('List product categories') and even enumerates the key fields returned (id, name, parent, has-children), so the agent knows exactly what comes back. It does not name or differentiate against sibling tools such as kiotviet_get_category, leaving the singular-vs-plural relationship 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?
'Set hierarchical to get the category tree' is a real usage cue for one parameter, but there is no guidance on when to prefer this over kiotviet_get_category, no mention of the incremental-sync path via last_modified_from, and no statement about paging through large catalogs. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers (code, name, phone, email, address, debt, total invoiced, reward points, groups). Contains personal data of the shop's customers. Filter by code, name, phone, group or last change. GET /customers.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Customer code. | |
| name | No | Filter by customer name. | |
| group_id | No | Only customers in this customer group. | |
| order_by | No | Sort field. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| include_total | No | Include financial totals (debt, total invoiced, points). | |
| contact_number | No | Filter by phone number. | |
| order_direction | No | Sort direction. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). | |
| include_customer_group | No | Include each customer's groups. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful context beyond annotations by noting that the data contains the shop's customers' personal data and by listing returned fields, though it does not discuss auth, rate limits, or pagination 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?
Three compact sentences front-load the core purpose, then add fields, privacy context, and filters. Every sentence contributes useful information without 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 list tool with no output schema, the description covers the resource, returned fields, privacy sensitivity, and main filters. Pagination and response-shape details are left to the schema, which is adequate though not fully described in prose.
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 documented in the schema. The description adds only a partial filter summary and does not explain sorting, pagination, or include_* parameters 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?
States a specific verb and resource: "List customers," and enumerates the customer fields returned. This clearly distinguishes bulk listing from the single-customer get_customer/get_customer_by_code 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?
The description gives filtering context (code, name, phone, group, last change) but does not explicitly say when to use this instead of get_customer or get_customer_by_code. Usage is implied rather than stated as when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales invoices (code, date, branch, customer, total, amount paid, status, lines). Filter by branch, customer, status, order, purchase-date range or last change. GET /invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | KiotViet status code(s) to include. | |
| order_by | No | Sort field. | |
| order_id | No | Only the invoice created from this sales order. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| branch_ids | No | Only these branches (see kiotviet_list_branches). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| customer_ids | No | Only invoices of these customers. | |
| customer_code | No | Only invoices of the customer with this code. | |
| include_payment | No | Include the payments. | |
| order_direction | No | Sort direction. | |
| to_purchase_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). | |
| from_purchase_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds real value by disclosing the return payload shape (code, date, branch, customer, total, amount paid, status, lines) despite there being no output schema. It omits pagination behavior and whether include_payment changes the payload size, which keeps 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 short sentences: identity plus returned fields first, filterable dimensions second, endpoint last. No filler and nothing redundantly restated.
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 read tool with no output schema, the description supplies the return field list and the filter surface, which is most of what an agent needs. Pagination semantics are only carried by the current_item schema text, so the description alone would leave a slight 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%, so every parameter is already documented, and the description merely echoes the filter categories. Its phrase 'order' is ambiguous between order_id, order_by and order_direction, and paging parameters are not addressed in the description at all, 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?
Names a specific verb (List) and resource (sales invoices) and enumerates the fields returned, which separates it from the singular get_invoice/get_invoice_by_code siblings. It never explicitly contrasts itself with those siblings, but the list-vs-get distinction is legible.
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 filter dimensions (branch, customer, status, order, purchase-date range, last change) imply when the tool is useful, and the GET /invoices endpoint is cited. There is no explicit when-to-use versus get_invoice or list_orders, and no stated prerequisites beyond what the schema hints (see kiotviet_list_branches).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales orders (code, date, branch, customer, total, status, lines, delivery). Filter by branch, customer, status, creation date (from) or last change (from/to). GET /orders.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | KiotViet status code(s) to include. | |
| order_by | No | Sort field. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| branch_ids | No | Only these branches (see kiotviet_list_branches). | |
| created_date | No | Only orders created at or after this date. | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| customer_ids | No | Only orders of these customers. | |
| customer_code | No | Only orders of the customer with this code. | |
| include_payment | No | Include the payments. | |
| order_direction | No | Sort direction. | |
| sale_channel_id | No | Only orders from this sales channel. | |
| last_modified_to | No | Only orders last changed up to this date-time (KiotViet toDate is a bound on the modification time, not the creation time). Use with last_modified_from. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). | |
| include_order_delivery | No | Include the delivery details. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the filter semantics (creation date vs last-change date), which is useful, but it omits anything about pagination behavior (current_item / next_item paging) or result-size 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?
Three short sentences, front-loaded with what the tool does and what it returns, followed by filters and endpoint. No filler; only minor tightening would improve it.
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, zero-required list tool with no output schema, the description covers purpose and filters but leaves out pagination mechanics and total/result-count behavior, which an agent needs to page correctly. It partially compensates by listing the response fields.
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 a subset of filters (branch, customer, status, creation date, last change from/to) but says nothing about order_by, page_size, include_payment, include_order_delivery or sale_channel_id, so it adds no 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?
Specific verb+resource ('List sales orders') with the returned field set and the filterable dimensions enumerated, plus the backing endpoint GET /orders. It is clearly a bulk-list operation versus the kiotviet_get_order / kiotviet_get_order_by_code siblings, though it never explicitly says so.
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?
Filter options imply when the tool is useful, but there is no explicit when-to-use guidance and no routing to alternatives (e.g. use kiotviet_get_order_by_code for a single known order, or kiotviet_list_invoices for invoices). The agent must infer the split from the 'List' vs 'Get' naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List price books (bang gia: name, active flag, validity dates, branches, customer groups). GET /pricebooks.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| include_branches | No | Include the branches each price book applies to. | |
| include_customer_groups | No | Include the customer groups each price book applies to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile needs no repeating. The description contributes the underlying HTTP endpoint and a summary of the record shape, but says nothing about pagination limits, rate limits or auth scoping that the annotations don't cover.
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 compact sentence with the resource and returned fields front-loaded, followed by the endpoint. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the field enumeration partially substitutes for a return-value description, and pagination is covered by the schema's current_item/page_size text. Missing only a note on total counts or paging termination, which is minor for a simple read-only listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so page_size, current_item, include_branches and include_customer_groups are already fully documented in the schema. The description's mention of 'branches, customer groups' only loosely gestures at the include flags and adds no syntax, defaults or pagination 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?
States the specific verb 'list' and resource 'price books', enumerates the fields returned (name, active flag, validity dates, branches, customer groups) and names the endpoint GET /pricebooks. The list-vs-get distinction from sibling kiotviet_get_price_book is implied by the verb but never made 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?
Usage is only implied by the name and verb 'list'; the description gives no guidance on when to pick this over kiotviet_get_price_book or other list tools, and no prerequisites are mentioned. An agent can infer this is the bulk-enumeration variant, but nothing in the text confirms it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products (code, barcode, name, category, base price, units, attributes). Optionally include stock per branch (include_inventory) and price-book prices. Filter by name, category, branch, active flag or last change. GET /products.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter by product name. | |
| order_by | No | Sort field. | |
| is_active | No | Only active (true) or inactive (false) products. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| branch_ids | No | Only these branches (see kiotviet_list_branches). | |
| category_id | No | Only products in this category (see kiotviet_list_categories). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| order_direction | No | Sort direction. | |
| include_inventory | No | Include the stock on hand per branch. | |
| include_pricebook | No | Include the price-book prices. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety needs no restating. The description still earns credit for disclosing beyond annotations that include_inventory adds per-branch stock and include_pricebook adds price-book prices, i.e., how response shape changes with flags, plus the underlying GET /products call. It omits pagination framing (page_size/current_item relationship), though the schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each carrying distinct information: returned fields first, then optional expansions, then filter dimensions. Front-loaded with the most useful fact (what comes back). Minor redundancy in repeating flag names already named in 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?
With 11 parameters and no output schema, the description sensibly fills the biggest gap by enumerating the returned fields, which nothing else supplies. Pagination semantics are left to the schema, which handles them adequately. A note on endpoint-specific behavior (rate limits, large result handling) would have made it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's parameter commentary ('include stock per branch (include_inventory)', 'price-book prices', 'last change') largely restates what the schema already documents and adds no format, default, or interaction detail 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 ('List products') and even enumerates the fields returned (code, barcode, name, category, base price, units, attributes), which immediately distinguishes it from the single-record siblings kiotviet_get_product / kiotviet_get_product_by_code. It stops short of naming those siblings explicitly, but the plural-list framing 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?
The description implies when to use it by listing the filter dimensions available (name, category, branch, active flag, last change) and the optional expansions, which lets an agent infer this is the browsing/search tool. However, it never states when NOT to use it (e.g., prefer get_product_by_code when you already have a code) and names no alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List goods receipts from suppliers (nhap hang: code, date, branch, supplier, total, lines). Filter by branch, status or purchase-date range. GET /purchaseorders.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | KiotViet status code(s) to include. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| branch_ids | No | Only these branches (see kiotviet_list_branches). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| include_payment | No | Include the payments. | |
| to_purchase_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). | |
| from_purchase_date | No | Date 2026-10-01 or date-time 2026-10-01T08:00:00 (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful context: the response fields (code, date, branch, supplier, total, lines), the filter surface, and the underlying endpoint. It does not discuss auth, rate limits, or pagination behavior, though the latter is partly captured in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the resource and scope, followed by filters and the endpoint. Nothing is redundant; the parenthetical field list is dense but earns its place because no output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description helpfully lists the returned fields, and all seven parameters are fully documented in the schema. It falls short on sibling differentiation and on explaining what integer status codes mean, which an agent may need to filter meaningfully.
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 documented in the schema; the description only restates the filter categories (branch, status, purchase date). It does not clarify the meaning of numeric status codes, explain include_payment or pagination usage, or add syntax 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 (list) and resource (goods receipts from suppliers), including the Vietnamese term 'nhap hang' and the fields returned, so the agent knows exactly what the tool reads. It does not distinguish itself from close siblings such as kiotviet_list_supplier_orders or kiotviet_get_purchase_order, leaving ambiguity between 'supplier orders' and 'purchase 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 names the available filter dimensions (branch, status, purchase-date range), which implies how to use it for filtered lists, and the GET endpoint signals a read. It gives no explicit guidance on when to choose this over kiotviet_list_supplier_orders or when to fetch a single record with kiotviet_get_purchase_order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customer returns (code, date, branch, customer, invoice, return total, lines). GET /returns.
| Name | Required | Description | Default |
|---|---|---|---|
| order_by | No | Sort field. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| include_payment | No | Include the payments. | |
| order_direction | No | Sort direction. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint (GET /returns) and the shape of returned fields, but says nothing about pagination, default page size, or that current_item should be fed from a prior reply's next_item — the most operationally relevant behavior for a list 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?
One compact sentence plus the endpoint, front-loaded with verb and resource; nothing is padded. The parenthetical field list is slightly dense but every item earns its place by previewing the payload.
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 6-parameter paginated list tool with no output schema, the field enumeration usefully describes returns, but the description omits pagination mechanics, filtering semantics (last_modified_from on shop-local time), and the sorting defaults. 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%, with enums, bounds and even the pagination hint on current_item documented inline, so the schema carries the full burden. The description adds no supplementary meaning about sorting, date filtering, or include_payment.
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 (List) and resource (customer returns), and enumerates the fields returned (code, date, branch, customer, invoice, total, lines), which makes clear it is the read-many counterpart to kiotviet_get_return. It stops short of naming that sibling explicitly, so the differentiation is inferable 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 'List' framing implies bulk retrieval versus the singular get_return/get_invoice tools, but the description never states when to prefer this tool, when not to, or what filters are available. Usage is implied by the verb rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock on hand and reserved quantity per product and branch. Filter by branch or last change. GET /productOnHands.
| Name | Required | Description | Default |
|---|---|---|---|
| order_by | No | Sort field. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| branch_ids | No | Only these branches (see kiotviet_list_branches). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| order_direction | No | Sort direction. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that reserved quantity is included alongside on-hand stock, but says nothing about paginating through large result sets beyond what the schema's current_item already implies.
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 fragments, front-loaded with the returned data, then filter options, then endpoint. No filler, though the telegraphic style leaves out connective context that could aid an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does name the key returned fields, but it does not state default scope (all branches when branch_ids is omitted) or pagination expectations. Adequate for a read-only list tool with fully documented parameters, but leaves avoidable 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%, so every parameter is already documented with defaults, ranges and cross-references (e.g. branch_ids points to kiotviet_list_branches). The description only echoes the branch and last-change filters, adding no syntax or behavioral 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 resource and payload: stock-on-hand and reserved quantity per product and branch, plus the underlying endpoint. It implicitly separates this inventory tool from catalog tools like kiotviet_list_products, but never names a sibling 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?
It hints at two usage modes (filter by branch, filter by last change) which implies when the tool is useful, but gives no explicit when-to-use/when-not-to-use guidance or alternatives among the ~30 sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders placed with suppliers (dat hang nhap: code, date, branch, supplier, status, lines, amount paid). Filter by branch, status, supplier or product text. GET /ordersuppliers.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | KiotViet status code. | |
| code_key | No | Order code. | |
| branch_id | No | Only this branch. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| product_key | No | Product code or name. | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| supplier_key | No | Supplier code, name or phone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /ordersuppliers) and confirms the result shape, but stays silent on pagination mechanics even though the schema's current_item refers to a 'next_item' from a previous reply — a behavior an agent needs to loop correctly.
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 compact sentences: the resource plus returned fields first, then the filter dimensions and endpoint. No filler, though the parenthetical field list and the trailing raw endpoint are dense shorthand that assumes familiarity with KiotViet terminology.
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 list tool with no output schema, the description does the work that matters most: it names the returned fields and the available filters, which is enough to decide relevance and construct a call. The only real gap is pagination behavior, which the schema hints at but the description never explains.
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 one of the 7 parameters is already documented in the schema and the baseline of 3 applies. The description restates the filterable dimensions but adds no semantics beyond the schema — e.g. it does not clarify the numeric KiotViet status codes or that product_key matches code or name.
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 orders placed with suppliers') and enumerates the fields returned (code, date, branch, supplier, status, lines, amount paid), which is more than a restatement of the title. However it does not distinguish this from the closely named siblings kiotviet_list_purchase_orders and kiotviet_get_purchase_order, leaving an agent to guess whether 'supplier orders' and 'purchase orders' are the same resource.
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 usage by listing the filter dimensions (branch, status, supplier, product text), which tells the agent this is the browsable/searchable list endpoint. It gives no explicit when-to-use or when-not-to-use guidance and never points at the single-record sibling (kiotviet_get_purchase_order) for fetching one known order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List suppliers (code, name, phone, email, address, debt, total invoiced). Filter by code, name, phone or last change. GET /suppliers.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Supplier code. | |
| name | No | Filter by supplier name. | |
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. | |
| include_total | No | Include financial totals (debt, total invoiced). | |
| contact_number | No | Filter by phone number. | |
| order_direction | No | Sort direction. | |
| last_modified_from | No | Only records changed at or after this date-time (shop local time). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the REST endpoint and that financial totals are gated behind include_total, but says nothing about pagination behavior or how large the listing may be.
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 compact lines: purpose and returned fields first, filters second, endpoint last. Efficient, though the parenthetical field list is somewhat crowded.
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?
Adequate for a read-only 8-param list tool with full schema coverage, but with no output schema the agent gets no guidance on pagination shape (next_item) or result envelope beyond the field roster.
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 carries a description, so baseline 3 applies. The description's mention of filter fields echoes the schema rather than adding format or matching 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?
Specific verb+resource (list suppliers) and an explicit field roster of what comes back. It does not distinguish itself from kiotviet_get_supplier or kiotviet_list_supplier_orders, so sibling differentiation is left to name 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?
Implied usage only: filtering by code/name/phone/last change is stated, which hints at search use cases, but there is no explicit when-to-use vs kiotviet_get_supplier (single lookup) or when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the shop's staff users (id, username, name, phone, email). GET /users.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Records per page, 1-100 (default 20). | |
| current_item | No | Record offset to start from (0 = first record). Pass the previous reply's next_item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the returned field set (id, username, name, phone, email) and the endpoint, which is genuinely useful context, but says nothing about pagination behavior, result caps, or whether the list is shop-scoped in practice.
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 clauses, front-loaded with the action and resource, then the return fields and endpoint. Nothing 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?
With no output schema, listing the returned fields is a real contribution, and annotations cover the safety profile. Only the pagination workflow is left implicit, and that is documented in the schema for current_item.
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 page_size and the current_item/next_item pagination pattern. The description adds no parameter meaning 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?
Clear verb+resource ('List the shop's staff users') with the returned fields enumerated and the underlying endpoint given. No sibling tool lists users, so differentiation is implicit rather than explicitly stated, which keeps it just below 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?
No guidance on when to use this versus direct lookups or any other tool, and no preconditions mentioned. The agent must infer that this is the entry point for enumerating staff.
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.
kiotviet_create_customerkiotviet_create_orderkiotviet_get_categorykiotviet_get_customerkiotviet_get_customer_by_codekiotviet_get_invoicekiotviet_get_invoice_by_codekiotviet_get_orderkiotviet_get_order_by_codekiotviet_get_price_bookkiotviet_get_productkiotviet_get_product_by_codekiotviet_get_purchase_orderkiotviet_get_returnkiotviet_get_supplierkiotviet_list_brancheskiotviet_list_cashflowkiotviet_list_categorieskiotviet_list_customerskiotviet_list_invoiceskiotviet_list_orderskiotviet_list_price_bookskiotviet_list_productskiotviet_list_purchase_orderskiotviet_list_returnskiotviet_list_stockkiotviet_list_supplier_orderskiotviet_list_supplierskiotviet_list_usersRead Sapo store products, orders, customers and stock levels; edit order notes and stock.
Read Megaventory products, stock, orders and partners; create clients, sales and purchase orders.
Read Smaregi stores, products, customers, stock and transactions; manage customers, products, stock.
Read store products, orders, customers, categories and coupons; adjust inventory and update orders.
Add one secure layer between your agents and this server.