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

Annotations already indicate the operation is not read-only and is destructive/idempotent. The description adds useful behavioral context: the token expires in 5 minutes and the call must follow explicit user confirmation, which clarifies the irreversible nature implied by destructiveHint.

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

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

Two sentences, no filler. The primary action is stated first, then the prerequisite and timing constraint, then the user-confirmation requirement. Every sentence earns its place.

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

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

With a single parameter, a clear prerequisite, expiration semantics, explicit user-confirmation condition, and an output schema present, the description covers everything needed to invoke this correctly alongside its sibling tools.

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

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

The schema only provides the token's type and length, with 0% description coverage. The description compensates by explaining that confirmation_token comes from create_purchase_order_draft and expires after 5 minutes, giving the parameter meaningful operational context.

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

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

The description uses a specific verb ('Sends') with a clear resource ('drafted purchase order') and even cites the endpoint (POST /purchaseorders). The title explicitly labels it 'step 2 of 2', distinguishing it from create_purchase_order_draft.

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 states when to call it ('only after the user explicitly confirms'), what prerequisite is required (confirmation_token from create_purchase_order_draft), and adds a time constraint (expires after 5 minutes). This gives an agent actionable go/no-go conditions.

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

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

The annotations only state that the operation is not read-only and not destructive, but the description adds crucial behavioral detail: the action is a draft only, nothing reaches KiotViet until confirmation, and the returned confirmation_token expires in 5 minutes. This transient-token and two-step commit context is exactly what an agent needs.

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

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

The description is two sentences with no filler. The first sentence front-loads the action and result; the second sentence states the critical non-effect of not sending the order until confirmation.

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-optional-param draft tool with an output schema and non-destructive annotations, it covers token expiry, the two-step confirmation flow, and how item input is sourced. A minor gap is what happens when neither suggestions nor items are available, but this does not block correct invocation.

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

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

With 0% schema coverage, the description compensates meaningfully by explaining that the tool can use 'current suggestions' when no items are given, or can take given product codes as an override. It does not fully describe qty semantics, but the param names and constraints already convey most of 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?

The description names a specific verb ('Drafts'), a specific resource ('KiotViet purchase order'), and the workflow position ('step 1 of 2'). It also clearly distinguishes this from the sibling confirm_purchase_order by stating that nothing is sent until that later step is called.

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

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

It clearly establishes this tool as the first step in a two-step flow and explains that confirm_purchase_order must follow only after the user approves. It does not explicitly list when not to use it or compare against other siblings, but the workflow context is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations by defining the threshold (minQuantity) and the urgency ordering (days of cover), which helps the agent understand what results to expect.

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

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

A single sentence that front-loads the core behavior and ordering with no filler. Every word contributes to the agent's understanding.

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 parameters, a rich annotation set, and an output schema present, the description fully covers what the tool does and how results are ordered. Nothing essential for invoking or interpreting the tool is missing.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is no parameter burden for the description to carry. The mention of minQuantity is domain context rather than a parameter explanation, which is appropriate.

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

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

The description clearly identifies the resource (products), the filter (at or below KiotViet minimum stock/minQuantity), and the ordering (most urgent first by days of cover). This distinguishes it from sibling tools like get_stock_level and get_top_movers.

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: the agent should use this when it needs products at or below minimum stock, sorted by urgency. However, it does not explicitly contrast with alternatives such as get_stock_level or suggest_reorder, leaving some routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral detail about the comparison logic (same weekday last week for single days), which is not captured elsewhere. No contradictions.

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

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

The description is a single, dense sentence with no filler. It front-loads the core output (revenue and units) and immediately clarifies the period options and comparison logic, making every word earn its place.

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

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

Given the single parameter, clear enum values, output schema presence, and annotations covering safety, the description provides all necessary context for an agent to call the tool correctly. It explains the comparison methodology, which is the only non-obvious aspect.

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 0%, so the description must compensate. It explicitly lists all enum values (today, yesterday, last_7_days, last_28_days) and explains their meaning via the comparison context. This fully compensates for the missing schema descriptions.

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

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

The description clearly states the tool returns revenue and units for specified periods, with a comparison to the previous equal period. This is a specific verb+resource and is clearly distinct from sibling tools about stock and reorders.

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

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

The description provides clear context about what data it returns (sales revenue and units) and the available periods. While it does not explicitly name alternatives or exclusions, the sibling tools are all in the stock/reorder domain, making the usage context unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world hints, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it can match by different identifier types and it asks which one when multiple matches exist, which is non-obvious behavior an agent would otherwise not know. It does not address auth, rate limits, or no-match behavior, but those are less critical given the simple read operation and the presence of an 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 core output front-loaded and the disambiguation behavior in the second sentence. There is no filler or repetition of schema/annotation details.

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

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

Given the tool's low complexity (one parameter), rich annotations, and an existing output schema, the description is complete for correct invocation. It covers what the tool returns, how the product is identified, and the ambiguous-match behavior. The only possible gap, no-match handling, is likely covered by the output schema or can be reasonably inferred.

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 0%, so the description must compensate, and it does: it explains that the single "product" parameter can be a name, product code, or barcode. This is essential semantic information beyond the schema's bare string type. It does not fully specify format rules, but for one parameter the meaning is sufficiently conveyed.

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

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

The description uses a specific verb and resource: it returns "On-hand quantity and days of cover for a product." It also specifies the lookup modes (name, product code, barcode) and explicitly signals that it asks for disambiguation when multiple products match, which distinguishes it from sibling tools that surface lists or summaries.

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

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

The title and description make clear this is for fetching stock level for a single product, and the search-by-identifier wording implies when it is appropriate. However, it does not explicitly contrast itself with alternatives like get_low_stock or suggest_reorder, and offers no exclusions or conditions for choosing this tool over siblings.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds the time-window scoping and the units-sold ranking basis, but it does not disclose additional behavioral traits such as empty-result behavior, pagination, or interpretation of 'bottom' beyond the direction parameter.

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

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

The description is a single, tightly scoped sentence with no filler. It front-loads the core behavior and avoids restating schema defaults or annotations.

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

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

The tool is simple, the output schema is present, and annotations are comprehensive, so the description does not need to explain return values. However, it lacks explicit usage guidance and does not fully describe the limit parameter, leaving minor but real gaps for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate. It effectively explains 'days' (last N days), 'direction' (top or bottom), and the ranking basis, but it does not explicitly explain 'limit' or how it caps the returned product list. The parameter names and defaults make some of this inferable, but a clear statement about limit would be stronger.

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

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

The description clearly identifies the resource (products) and the metric (units sold) over a configurable time window, and the title 'Best and slowest sellers' reinforces the meaning. It is distinguishable from siblings like get_low_stock or get_sales_summary, though it lacks an explicit verb like 'returns' or 'lists'.

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 is provided about when to choose this tool over alternatives, and none of the sibling tools are mentioned. The description implies its use for top/bottom seller analysis, but there are no explicit conditions, exclusions, or comparisons.

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

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

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context by defining which items are included (at/below minimum) and exactly how quantity is calculated. This goes beyond the annotations without contradicting them.

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

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

The description is compact and efficient, with the core purpose front-loaded in the first sentence. The formula is presented clearly and the read-only modifier is a single useful word. Every part earns its place.

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

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

For a tool with no input parameters, the description fully explains what it does, what data it considers, and the formula for output quantities. The output schema exists to describe return structure, so the description does not need to cover that. No meaningful context is missing.

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

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

The tool has zero parameters, so there is no parameter documentation burden. The description explains the internal data inputs used (lead time, average daily sales, on-hand quantity) even though they are not user-supplied parameters. This is more than adequate for a parameterless tool.

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 clear verb and resource: suggest reorder quantities for items at/below minimum. It also gives the exact quantity formula, distinguishing it from generic stock viewers and order-creation tools. The read-only note reinforces that this is an advisory, not a mutation, tool.

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

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

The phrase 'What to reorder now' clearly signals when to use the tool: during reorder planning. It does not explicitly name alternatives like create_purchase_order_draft or get_low_stock, but the read-only designation and focus on suggested quantities imply its role versus sibling tools. Some explicit exclusion guidance would improve it.

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