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

Even though annotations mark readOnlyHint=false, the description goes further by warning that this posts a real transaction to the merchant's books, affects stock and reporting, and supports only a single payment type. These side effects and constraints are not visible in the structured annotations and are crucial for safe invocation.

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

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

Three short sentences with no fluff: the core action is front-loaded, then the critical confirmation warning, then the concrete payment limitation. Every sentence earns its place.

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

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

For a high-complexity mutation tool with no output schema, the description covers the essential behavioral warnings and the key API limitation. It does not describe the created receipt response or error conditions, but the schema still provides structural detail for the parameters, making the definition broadly sufficient.

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 only 30%, so the description carries a heavy burden, but it only references 'line items' and 'total' broadly and the single-payment constraint. It does not explain most of the 10 parameters such as store_id, customer_id, discounts, modifiers, or taxes, leaving the agent under-informed for a complex payload.

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 'Record a sale,' a specific verb and resource, and then explains that it posts a real transaction affecting books, stock, and reporting. This clearly distinguishes it from sibling receipt tools like list_receipts, get_receipt, and refund_receipt.

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

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

The description explicitly tells the agent to confirm line items and totals with the user before invoking this side-effectful tool, and it flags a concrete limitation: only one payment type is supported, so split tender is not possible. It lacks explicit mention of alternatives such as refund_receipt for reversals, but the usage context is clear.

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

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

Annotations already indicate this is a write operation and not idempotent, so the description does not need to restate that. It adds valuable behavioral context beyond the annotations: the endpoint will receive live merchant data and therefore requires user-provided consent. No contradiction with the annotations was found.

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 wasted words. The core action is front-loaded in the first sentence, and the second sentence delivers an important user-consent caveat that earns its place.

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

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

For a simple creation tool with three parameters and no output schema, the description provides the key operational consequence (live data delivery) and the critical authorization guardrail. It could be slightly more complete by addressing the status parameter, but the schema and enums cover the remaining essentials.

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

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

The input schema already describes the url and type parameters with useful detail, and the description loosely mirrors those semantics. However, the description does not clarify the optional status parameter or its default behavior, so it adds limited meaning beyond the schema and enum constraints.

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 ('Subscribe') with a clear resource ('an https endpoint') and target ('a Loyverse event'), making the tool's function immediately recognizable. It also distinguishes this from sibling tools like loyverse_list_webhooks by describing the creation of a live-data subscription rather than a read or listing operation.

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

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

The description gives a clear practical usage condition: only register a URL the user has provided, because the endpoint will receive live business data. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to know when invoking this tool is appropriate.

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

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

The description adds substantial behavioral context beyond the annotations: deletion removes live business data, is irreversible via the API, requires explicit user consent, and deleting an item cascades to variants and stock history. This meaningfully informs an agent about the destructive nature and side effects of the call.

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

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

The description is three sentences, each earning its place: the first states the core action, the second conveys irreversibility and the confirmation requirement, and the third details an important cascade effect. It is front-loaded with the main purpose and wastes no words.

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 (two parameters, both documented) and the annotations already provide destructive and read-only flags. The description adds essential safety guidance and a key side effect. It does not explain return values or error behavior, but no output schema exists and the destructive nature is well covered, so this is a minor 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?

The input schema already covers all parameter meanings with 100% coverage: 'resource' has a descriptive enum and 'id' is explained. The description adds no new parameter syntax or format details, so it meets the baseline but does not exceed what the schema already provides.

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

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

The description uses a specific verb ('Delete') and a clear resource ('one record from the merchant's Loyverse account'). It is immediately obvious what operation this tool performs, and the generic scope is clarified by the resource parameter. No sibling tool competes with this delete operation, so no further differentiation is needed.

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 clearly establishes when to use the tool: when a record should be deleted. It goes further by mandating user confirmation before invocation, which is strong guidance for safe use. It does not explicitly compare against alternatives, but none of the sibling tools are delete operations, so this is a minor gap.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful context that the response includes loyalty points and visit history totals, but it does not disclose error behavior, idempotency oddity, or any rate/authentication considerations.

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

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

One clean, front-loaded sentence contains the operation, scope, and key return fields 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 operation with readOnly annotations, the description covers the essential operation and the notable return fields. It omits what happens on a missing customer or how to obtain the customer_id, but those gaps are minor for this simple 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?

With 0% schema description coverage, the description must compensate, but 'by id' only restates what the parameter name customer_id already communicates. It provides no format, source, or uniqueness information for the id, adding minimal meaning beyond the schema.

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

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

The description uses the specific verb 'fetch' with the resource 'one customer by id', clearly distinguishing it from list/upsert siblings. The added detail on loyalty points and visit history totals further specifies this tool's unique return content among the sibling get tools.

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

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

The phrase 'one customer by id' implies this is for a single known customer, while list_customers would be for multiple, and upsert_customer for creation/update. However, no explicit when-to-use or when-not-to-use guidance naming alternatives is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the basic fetch action, such as not-found behavior, return payload, or any special response semantics.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to understanding the tool's core operation.

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 single-resource getter with one required parameter and read-only annotations, the description is largely sufficient. It does not describe the return shape or error behavior, but no output schema exists and the operation is straightforward enough that this 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 0%, so the description must clarify the parameter's role. 'Fetch one employee by id' clearly maps the employee_id parameter to the lookup key, providing meaningful semantic context beyond the bare schema property name and type.

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

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

The description states a specific verb ('Fetch'), a specific resource ('one employee'), and the lookup mechanism ('by id'). It clearly distinguishes this tool from list_employees and other getters by 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?

The description implies usage when a single employee_id is known, but it does not explicitly say when to prefer this over list_employees or how it relates to sibling tools. The guidance is reasonable but left 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=true and destructiveHint=false, covering the safety profile. The description adds useful behavior by indicating this is a snapshot of "current" stock and implying unfiltered results can be large. It does not, however, disclose pagination, default limits, or response shape.

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 with no filler. The core purpose is front-loaded, and the filtering guidance earns its place by adding actionable parameter context.

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

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

For a tool with five optional parameters and no output schema, the description is incomplete. It does not explain limit semantics, pagination, how updated_at filters behave, or what the returned inventory response looks like, leaving an agent to guess at important invocation details.

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

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

Schema description coverage is only 40%, so the description must compensate for the remaining parameters. It adds meaning only for store_ids and variant_ids via the filtering advice; limit and updated_at_min/max receive no behavioral or semantic explanation beyond their raw schema types.

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: "Read current stock per variant per store." This clearly identifies the tool's purpose and scope, distinguishing it from write operations like loyverse_set_inventory, though it does not explicitly contrast with sibling get/list tools.

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

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

The description gives clear context for when to use the tool: whenever current stock levels per variant and store are needed. It also provides practical usage guidance by advising filters to keep results small, though it does not explicitly state when not to use it or name alternatives.

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

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

The description adds that the result includes all variants, which is beyond the readOnlyHint and destructiveHint annotations. It also aligns with the read-only nature, and no contradictions exist with the annotations.

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

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

One sentence, no fluff, front-loaded with the core action and scope. It is appropriately concise.

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

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

For a simple get-by-id tool with one parameter and no output schema, the description sufficiently states what the tool does and what it returns (item with variants). No critical information is missing.

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

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

The schema already documents item_id as 'The item id.', so the description adds no additional parameter semantics. With 100% schema coverage, 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 the specific action (Fetch), the resource (one catalogue item), and the method (by id), and notes it includes variants. This clearly distinguishes it from list_items and get_variant tools.

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

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

The description implies usage when you have a specific item_id and need the item with its variants. It doesn't explicitly compare to alternatives like list_items, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by stating that the result determines currency formatting for all other operations and by listing the fields returned, which matters because there is no output schema. It does not go into response structure, but that is minor for a simple profile fetch.

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

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

Two sentences with no filler. The action and resource are front-loaded, the returned fields follow, and the usage directive closes the description. Every sentence earns its place.

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

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

For a zero-parameter, read-only tool with no output schema, the description provides the key return fields and the practical reason to call it first. Nothing an agent needs to decide to invoke it 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 the schema coverage is 100%, so there is nothing for the description to add about parameters. This matches the baseline of 4 for parameterless tools.

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 ('Fetch'), names the resource ('account profile'), and enumerates the returned fields (business name, country, currency, decimal places). It is clearly distinct from sibling tools like loyverse_list_stores or loyverse_get_customer because it targets the merchant account itself.

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 explicit usage timing: 'Call this first to know how to format money in every other result.' This tells the agent when to invoke it and why, which is strong guidance for a zero-parameter tool with no natural alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scoping detail that exactly one receipt is fetched by receipt number, but it does not disclose error behavior, return format, or whether the receipt number must be globally unique. This is acceptable but not additive beyond the annotations.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning, making it an example of efficient specification.

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

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

This is a simple single-parameter read-only fetch, and the description provides enough information for selection and invocation. The absence of return-format or not-found behavior is a minor gap, but given the low complexity and existing annotations, the description is reasonably complete.

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

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

The schema provides no description for receipt_number, so the description carries the burden. It only restates that lookup is 'by its receipt number,' which adds little beyond the parameter's own name. No format, source, uniqueness, or validation details are provided, so the parameter semantics remain thin.

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

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

The description states a specific verb ('Fetch'), a precise resource ('one receipt'), and the identifying key ('receipt number'). This clearly distinguishes it from sibling operations like loyverse_list_receipts or loyverse_refund_receipt without ambiguity.

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

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

The description implies the tool is for retrieving a single receipt when its receipt number is known, but it does not explicitly mention when to use an alternative such as loyverse_list_receipts for multiple receipts. There is no exclusion or routing guidance, so the usage context is only implicit.

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 communicate read-only and non-destructive behavior; the description adds the cardinality of returning exactly one shift but no further behavioral context such as error responses or whether missing IDs produce null or an error. This is acceptable for a simple getter but not rich.

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

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

The description is a single front-loaded phrase with no filler; every word carries semantic weight.

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 one required parameter and no output schema, the description plus annotations are nearly sufficient: an agent knows to supply shift_id and that the result is a single shift. It lacks explicit mention of alternate list usage or edge cases, but none are essential for basic 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?

Schema coverage is 0%, and the description only says 'by id' rather than naming shift_id. It adds minimal meaning beyond the schema, though the single parameter's purpose is inferable from its name and the description.

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

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

The description states an explicit action ('Fetch'), a specific resource ('shift'), and a retrieval criterion ('by id'), which clearly distinguishes it from list-oriented siblings like loyverse_list_shifts. No ambiguity about what the tool does.

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

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

'By id' implies the tool should be used when a single shift identifier is available and a unique shift is wanted, which distinguishes it from loyverse_list_shifts. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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 already declare readOnlyHint=true and destructiveHint=false, and the description adds no additional behavioral context such as response shape, not-found behavior, or permission requirements. It is consistent with the annotations but does not go beyond 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 single sentence is entirely functional, front-loads the action and object, and contains no filler or repetition. It is an appropriate size for a simple getter.

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-only getter with annotations covering the safety profile, 'Fetch one store by id' is nearly complete. It lacks explicit return or error details, but those are less critical for such a simple 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?

Schema description coverage is 0%, and the description only echoes that the tool fetches by id rather than explaining the store_id format or meaning beyond the property name. The schema already shows store_id is a required string, so the description adds very little semantic value.

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

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

The description 'Fetch one store by id' names a specific verb (fetch), a resource (store), and the selecting key (id), making it clearly distinct from sibling list_stores. An agent can tell this is a singular retrieval operation with no ambiguity.

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

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

The only usage cue is the implicit implication that a store_id is needed to retrieve one specific store. There is no explicit statement about when to use this versus list_stores or other getters, so the agent must infer the right context.

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

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

The description simply restates the operation ('Fetch') and adds no behavioral details beyond what annotations already declare (readOnlyHint=true, destructiveHint=false). It does not disclose error cases, response format, or any edge behavior, so it adds minimal value beyond the annotations.

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

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

The description is a single, concise sentence with no redundancy. It is well-structured and front-loaded, though it may be too terse, it earns its place as an efficient statement.

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 simplicity of the tool (one parameter, read-only, no output schema), the description is adequate for basic invocation but omits expected return value or error behavior. An agent can likely infer that it returns a supplier object, but it is not explicitly stated.

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 carries the burden of explaining the parameter. It does clarify that supplier_id is the identifier ('by id'), but provides no format, constraints, or additional meaning. The description only partially compensates for the missing schema detail.

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 ('Fetch') and resource ('supplier') with a specific scope ('one... by id'). However, it does not differentiate from sibling get tools (e.g., get_receipt, get_store) beyond the resource name, so it lacks explicit sibling distinction.

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

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

No guidance on when to use this tool versus list_suppliers or other get tools. The usage is implied (when you need a single supplier by ID), but no exclusions or alternatives are mentioned, leaving the agent to infer context.

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 cover readOnlyHint=true and destructiveHint=false, so the safety profile is provided. The description adds the useful context that the response includes per-store pricing, but it does not mention error behavior, response shape, or authorization requirements; these are minor gaps for a simple read-only getter.

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

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

A single front-loaded sentence with no filler. Every word adds meaning, and the per-store pricing detail provides valuable output context without bloating the description.

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-only getter, the description plus annotations cover what an agent needs to invoke it correctly: the id to pass, the expected output scope, and the safety profile. The absence of an output schema is partly mitigated by the explicit 'per-store pricing' detail, though full response fields are not enumerated.

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

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

The schema has one string parameter, variant_id, with 0% schema description coverage. The description maps it via 'by id', which is minimal but adequate for an obvious get-by-id call; it does not clarify id format, provenance, or uniqueness beyond what the schema already states.

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 ('Fetch'), resource ('variant'), selection criteria ('by id'), and a notable output detail ('including its per-store pricing'). This clearly distinguishes it from sibling tools like loyverse_list_variants (plural listing) and loyverse_upsert_variant (write operation).

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

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

The description implies usage when a variant id is available ('Fetch one variant by id'), but it does not explicitly say when to prefer this over loyverse_list_variants or how to obtain the id. No alternatives or exclusions are named, so usage 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.

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

The description adds no behavioral context beyond the title and annotations. The annotations already declare readOnlyHint=true and destructiveHint=false, but the description does not disclose pagination behavior, filtering semantics, or response format, which would be valuable for a list operation.

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

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

The description is extremely short—just four words—and to the point. It is not verbose, and while it could benefit from additional context, the brevity is not harmful for a simple list operation.

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 straightforward list tool with three optional parameters and no output schema, the description is minimal but not inadequate. It lacks details on pagination, filtering by category IDs, or return structure, but given the low complexity and presence of schema descriptions for most parameters, it is acceptable.

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

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

The schema already provides descriptions for limit and show_deleted, covering two of three parameters (67% coverage). The description itself mentions none of the parameters, and categories_ids lacks schema documentation. With moderate schema coverage, the description adds no compensating value, so a baseline of 3 is appropriate.

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

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

The description states the verb 'list' and the resource 'item categories', making the primary purpose clear. It does not explicitly differentiate from sibling list tools (e.g., loyverse_list_items) beyond the noun, but the category resource is distinct enough that an agent can infer the intent.

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 on when to use this tool versus alternatives. The description does not mention any prerequisites, typical use cases, or conditions under which a sibling tool would be more appropriate, leaving the agent to infer from naming alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the returned summary fields, but says nothing about pagination, result completeness, or how the openWorldHint applies to this list operation.

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

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

Two crisp sentences with no filler. The main purpose is front-loaded, and the email filter use case is stated immediately after, making the description easy to scan and 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 list tool with 7 optional parameters, no output schema, and an openWorldHint annotation, the description is functional but thin. It covers the core purpose and output fields, but omits guidance on pagination, parameter combinations, and the relationship to loyverse_get_customer.

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

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

The only parameter meaning added beyond the schema is that email can be used to find a single person. The schema already documents email and the timestamp bounds, but `limit` and `customer_ids` remain undocumented in both the schema and description, and filter combination behavior is not explained.

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 ('List') and resource ('loyalty customers') and adds helpful output detail (visit counts, total spend, points balance). It is distinct enough from siblings like loyverse_get_customer, though it does not explicitly contrast itself with that 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 'Filter by email to find one person' gives a concrete use case for the tool. However, it does not mention alternatives such as loyverse_get_customer, nor does it explain when not to use this tool versus a get/list sibling.

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 already state readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds a small amount of scope ('configured on the account') but does not explain behavioral aspects such as pagination, inclusion of deleted discounts, or the meaning of the openWorldHint/idempotentHint annotations. No contradiction with annotations.

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

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

The description is a single front-loaded sentence with no filler: it states the action, the resource, and the scope. Every word 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 basic invocation, the description is adequate: no required parameters, and the read-only annotations cover the safety context. However, the tool accepts six optional filters, has no output schema, and the description does not mention response shape, filtering semantics, or whether deleted discounts appear, so it is not fully complete for nuanced use.

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

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

The description adds no meaning beyond the input schema for the six parameters. Two parameters (`discount_ids`, `show_deleted`) lack schema descriptions, and the description does not compensate for them or clarify filtering behavior. Schema coverage of 67% is not high enough to offset this gap.

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 ('List') and a clear resource ('discounts'), with an account-level scope ('configured on the account'). It is immediately distinguishable from the sibling write tool `loyverse_upsert_discount`, so an agent can tell this is the read-only lookup.

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

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

There is no guidance about when to prefer this tool over alternatives, no mention of the write sibling `loyverse_upsert_discount`, and no conditions or exclusions. The only usage signal is implied by the verb 'List', which is not enough guidance.

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

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

Annotations already cover the safe read-only behavior (readOnlyHint=true, destructiveHint=false), so the description does not need to restate that. It adds minor behavioral context by noting that employee roles are included and that other entities reference employees by id, but it does not describe pagination, soft-delete handling, or response shape.

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

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

Two short sentences with no filler; the core purpose is front-loaded and the second sentence adds relevant cross-reference context. Every word 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 read-only list tool with no required parameters and a well-documented schema, the description is mostly sufficient: it names the returned resource and clarifies the employee-id relationship used by receipts/shifts. It could be slightly more complete by mentioning pagination or the employee_ids filter, but these are already covered in the schema and the operation is low-risk due to readOnlyHint.

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 high (86%), with all parameters except employee_ids having descriptions, so the schema carries most parameter semantics. The description adds no parameter-level details, and employee_ids remains undocumented, but the baseline of 3 applies because the schema provides sufficient guidance for most parameters.

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

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

The description states a specific action and resource: 'List employees and their roles'. This clearly differentiates it from the sibling get_employee tool (which would return a single employee) and from other list_* tools by naming the exact resource. The added note that receipts and shifts reference employees by id gives extra purpose context.

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

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

The description implies when to use the tool through 'Receipts and shifts reference employees by id' – i.e., for resolving employee references in other records – but it does not explicitly state when to prefer this over get_employee or other list tools. There are no exclusion criteria or alternative tool names mentioned.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the useful detail that results include variants, prices, and SKUs, but it does not disclose pagination, default limits, or soft-delete behavior beyond what the schema already exposes.

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 states the core function, and the second sentence provides a practical use case, making it efficient and easily scannable.

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 rich schema documentation and safety annotations, the description is largely sufficient. It communicates the key return content and the motivating use case, though an explicit note about pagination or default limits would make it fully complete.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the input schema. The description does not need to explain each parameter and adds no new parameter-level meaning beyond the general purpose of finding variant_id.

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

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

The description clearly states it lists catalogue items with variants, prices, and SKUs, and highlights the practical purpose of finding variant_id. It is specific enough about the resource and action, though it does not explicitly distinguish itself from sibling loyverse_list_variants.

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 concrete guidance: use this tool to find variant_id needed by inventory and receipt tools. This provides clear context for when to call it, but it does not mention exclusions or alternative sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds that the tool returns both groups and their options, which is useful. However, it doesn't disclose pagination behavior, default limits, or whether soft-deleted records are excluded by default—though the schema's show_deleted parameter hints at that. No contradiction with annotations.

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

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

A single, efficient sentence that front-loads the action and resource, then gives a concrete example of the content. No wasted words. It could add a bit more context, but for a list tool this is appropriately concise.

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 7 optional parameters and no output schema, the description is adequate but not complete. It doesn't mention pagination behavior, default limit, or how modifier_ids filters results. The annotations cover safety, and the schema covers parameters, but an agent might still be unsure about the return shape or how to page through results.

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 86%, so the schema already documents most parameters (limit, show_deleted, timestamps). The description adds the meaning of 'modifier groups and their options' but doesn't explain the modifier_ids parameter or how filtering interacts with pagination. Baseline 3 is appropriate since the schema carries most of the semantic weight.

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 ('modifier groups and their options'), with examples of what those options are ('sizes or extras'). It clearly distinguishes this from sibling tools like loyverse_upsert_modifier (which writes) and other list_* tools (which target different resources). It doesn't explicitly name a sibling, but the resource is specific enough that an agent can tell it apart.

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 a read-only listing use case, and the readOnlyHint annotation reinforces that this is for retrieval rather than mutation. However, it provides no explicit guidance on when to choose this over loyverse_upsert_modifier or loyverse_list_items, and no mention of pagination or filtering strategies. The context is clear but exclusions/alternatives are not stated.

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 provide readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the data is account-scoped and that returned IDs are needed for receipt creation, but it does not mention pagination, deleted-type filtering, or whether soft-deleted types appear by default. This is acceptable but not rich behavioral disclosure.

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

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

The description is two tight sentences with no filler. The first sentence front-loads the operation and scope, and the second supplies a practical downstream dependency. Every sentence earns its place.

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

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

For a read-only list operation with annotations covering safety, the description is mostly complete: it states the account scope and the receipt-creation use case. It could add pagination or response-shape details, but the schema documents the filters and there is no output schema, so the description carries a reasonable amount of context.

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

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

Schema descriptions cover 4 of 6 parameters, but the description adds no parameter-level meaning. The two undocumented parameters, show_deleted and payment_type_ids, are not explained, and the phrase 'payment_type_id' is usage guidance rather than parameter documentation. The description fails to compensate for the remaining schema gaps.

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

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

The description states a specific verb and resource: 'List the payment types configured on the account.' This clearly identifies what the tool returns and distinguishes it from the sibling list_* tools, all of which target different resources. The second sentence reinforces the purpose by connecting it to receipt creation.

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 a clear use context: payment types must be fetched before creating a receipt, so an agent knows when this tool is relevant. It does not explicitly state when not to use it or name alternatives, but no sibling tool overlaps with listing payment types, so the guidance is adequate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds minimal behavioral information beyond that, merely stating 'list' and 'registered to the account.' It does not disclose how the optional parameters (store_id, show_deleted) affect behavior, pagination, or output format, so it adds little value beyond the annotations.

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

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

The description is a single, front-loaded sentence that is concise and free of unnecessary words. It clearly communicates the action and resource without fluff. However, its brevity sacrifices parameter details, though that is not the focus of this dimension.

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 with no required parameters and annotations cover safety, but the description does not mention the optional parameters or their purpose, nor does it indicate the response shape. Given the schema coverage is 0%, the description should have explained the parameters to make the tool fully understandable. It is incomplete for an agent to call correctly without additional context.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It does not mention store_id or show_deleted at all, leaving the agent to infer their meaning solely from names. This is a complete gap in 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 (List) and resource (till devices) with scope ('registered to the account'), clearly distinguishing it from other list tools like loyverse_list_stores and from the write counterpart loyverse_upsert_pos_device. It is unambiguous and directly matches the tool name.

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

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

The description gives a clear context (listing POS devices) but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or conditions. Usage is implied rather than stated, so it does not meet the 'explicit' bar for a 4.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the behavioral limitation about the Unlimited Sales History add-on, including a concrete error condition for older date ranges, which goes beyond the annotations.

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

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

Two concise sentences with no filler. The first sentence states the core function and scope; the second delivers a critical operational limitation. Every word 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?

The description discloses the key add-on limitation, which is valuable. However, for a list tool with 11 filters and no output schema, it omits expected response shape, pagination behavior, or default ordering, leaving an agent partially uncertain about what the call will return.

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

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

The description does not explain any of the 11 parameters, and the schema coverage is only 55%. Several parameters (e.g., store_id, receipt_numbers, since/before_receipt_number) lack descriptions, and nothing in the description compensates for those gaps. The mention of line items, taxes, and discounts relates to response content, not 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 clear verb and resource: 'List sales and refund receipts with their line items, taxes, discounts and payments.' This distinguishes it from single-receipt and mutation tools, though it doesn't explicitly name sibling alternatives.

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

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

The description provides important context about the 31-day data window and the payment-required error for older ranges, which informs usage. However, it does not explicitly mention when to prefer this tool over get_receipt or sales_summary, or when not to use it.

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

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

The readOnlyHint and destructiveHint annotations already establish that this is a safe read operation, so the description only needs to add context, and it does by naming the returned cash amounts and reconciliation purpose. It does not add richer behavioral detail such as pagination, ordering, or scoping behavior, so it stays at a mid score.

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 short sentences with no filler. It leads with the core action and resource, then adds a practical use case, so every sentence earns its place.

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

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

For a read-only list tool with no required parameters, this is nearly sufficient: the annotations cover safety and the description states what the resulting shift data contains. However, it omits any mention of the limit parameter or store_ids, and with no output schema and 50% schema coverage, an agent still needs to infer some call semantics.

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 only 50%, with limit and store_ids lacking any schema descriptions, and the tool description does not explain those parameters. The phrase 'reconcile a day's cash drawer' only weakly implies date filtering, but the description adds no real meaning beyond the schema's own created_at_min/max labels.

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 a specific verb ('List'), a concrete resource ('till shifts'), and the key data returned ('opening and closing cash amounts'). It is clearly distinct from get_shift in that it lists many shifts; however, it does not explicitly name the alternative for retrieving a single shift.

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 this to reconcile a day's cash drawer' gives a concrete use case and context for when to reach for this tool. It does not mention exclusions or explicitly compare against sibling get_shift, but the guidance is clear enough for selection.

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 and destructiveHint false, covering safety. The description adds minimal behavioral context beyond the returned addresses and downstream use. No pagination or rate-limit detail is provided, but the annotation bar lowers the need.

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

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

Two short sentences with no filler. The main action and output are front-loaded, and the second sentence adds high-value downstream usage context in few words.

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 list tool with no output schema, it gives the core purpose and usage context but omits parameter semantics and any response shape or pagination notes. An agent would need to infer or probe the behavior of store_ids and show_deleted.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It does not mention how store_ids filters results or what show_deleted does, leaving the agent to guess from property names alone.

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

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

States a specific verb and resource ('List the stores on the account') with output detail ('with their addresses'). The plural scope and mention that other filters use store_id from here clearly distinguish it from the singular get_store tool.

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

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

The description provides clear contextual guidance: this is the source of store_ids for filters elsewhere. It does not explicitly name alternatives or state when not to use it, but the implied use case is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds that contact details are returned, which is minor but useful context. It does not disclose pagination behavior, default limits, or how soft-deleted records are handled, but given the annotations, the bar is lower; this description provides some value beyond the schema.

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

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

The description is a single, concise sentence with no extraneous words. The core purpose is front-loaded and the added detail about contact details is valuable without clutter.

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 list tool with three parameters and no output schema, the description is incomplete. It does not explain pagination, the default limit, how to use suppliers_ids for filtering, or whether soft-deleted records are included by default. The schema covers some parameter semantics, but an agent would need more context to use this tool correctly in complex scenarios.

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 67%: limit and show_deleted have descriptions, but suppliers_ids lacks one. The tool description does not mention any parameters, so it does not compensate for the missing suppliers_ids documentation. The schema itself handles the described parameters, so a baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List suppliers with their contact details.' It clearly indicates a read-only listing operation and adds the nuance that contact details are included, which distinguishes it from a simple count or ID-only list. However, it does not explicitly differentiate from sibling tools like get_supplier, though the plural 'suppliers' makes the intent evident.

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

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

The description provides no guidance on when to use this tool versus alternatives like loyverse_get_supplier for a single supplier or loyverse_upsert_supplier for writes. The plural form implies listing multiple records, but there is no explicit statement of the use case or exclusions, leaving the agent to infer.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the specific content detail (included/added to price), but doesn't mention any other behavioral aspects like rate limits or pagination. It provides minor value beyond the annotations.

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

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

A single, clear sentence with zero filler. It is appropriately front-loaded with the core purpose and the key distinguishing detail. Perfect conciseness.

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

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

For a list tool with no output schema and 6 optional filter parameters, the description is minimal. It doesn't explain that parameters are filters, or describe the return format. While annotations cover safety, the description leaves some operational details ambiguous, though the schema partially fills the 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 67% (4 of 6 parameters have descriptions), so the description should compensate for the undocumented tax_ids and show_deleted parameters. However, it provides no parameter guidance whatsoever, leaving those two parameters entirely unexplained.

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 ('List') and resource ('tax rates'), and adds the distinctive detail of whether each tax is included in or added to the price. This clearly distinguishes it from sibling tools like loyverse_upsert_tax and other list operations.

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

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

The description makes the tool's purpose obvious for listing tax information. While it doesn't explicitly mention alternatives or exclusions, the context of the sibling tools (upsert_tax vs list_taxes) makes the usage clear without needing explicit routing.

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 signal readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds useful conceptual context about variants being sellable units, but it does not describe behavior such as pagination, default limits, or open-world implications beyond what annotations and schema already convey.

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

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

Two short sentences with no filler. The first sentence front-loads the action and key filtering capability, while the second provides a concise definition that helps distinguish variants from items; every word 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 read-only list operation with no required parameters and strong schema descriptions, the description is largely complete. It explains what a variant is and that filtering is optional, while the schema covers the individual filters. The absence of output schema and pagination details is a minor gap, but the combination of description, annotations, and schema is sufficient for a competent 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 high at 89%, and most parameters already have meaningful descriptions such as 'Exact SKU match' and 'Include soft-deleted records.' The description adds a conceptual mapping to 'SKU or parent item,' but this largely restates what the schema already communicates, so it meets the baseline without elevating 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?

The description clearly states the operation ('List item variants') and clarifies the resource by defining a variant as 'the sellable unit that inventory and receipts refer to.' It does not explicitly differentiate from sibling tools like get_variant or list_items, but its scope is unambiguous enough for selection.

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

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

The description implies usage through 'optionally filtered by SKU or parent item,' indicating this is the list-oriented lookup for variants. However, it gives no explicit when-to-use guidance, exclusions, or comparison with nearby siblings such as get_variant or list_items, so the agent must infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds minimal extra behavioral context ('on the account') but does not disclose details like response format, pagination, or whether deleted webhooks are excluded. With annotations covering the main safety aspects, this is acceptable but not rich.

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

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

A single, front-loaded sentence with zero wasted words. The verb 'List' appears first and the object is explicit. This is the ideal length for a simple list operation.

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 zero-parameter, read-only list tool with no output schema, the description is fully sufficient. The agent can invoke it correctly with no additional information. Nothing essential 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 the schema properties are empty, so schema coverage is trivially 100%. The description adds no parameter information because none is needed. Per the rubric, 0 params warrants a baseline of 4.

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 ('List'), a specific resource ('webhook subscriptions'), and scope ('on the account'). It is distinct from sibling tools like create_webhook and delete, leaving no ambiguity about what this tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives. While it is implicitly the read-only listing counterpart to create_webhook, it never explicitly mentions when to choose this over other tools, leaving the agent to infer usage from context.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds crucial context: 'moves money and restores stock' and 'cannot be undone through the API'. This goes beyond the annotations by specifying the concrete side effects and irreversibility.

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

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

Three sentences with no filler. The main action is front-loaded, followed by side effects and a safety note. 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?

The description covers the core purpose, side effects, and a usage caution, but omits details about optional parameters and does not describe the response format (no output schema). It also leaves ambiguity about how to specify a full refund given line_items is required. Adequate for basic use but incomplete for a mutation tool with multiple undocumented parameters.

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 only 33%, leaving source, store_id, and employee_id undocumented. The description does not explain these parameters or clarify how 'full' refunds map to the required line_items array. It adds little meaning beyond the schema, failing to compensate for the low coverage.

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

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

The description states a specific verb ('Issue a refund'), the resource ('an existing receipt'), and the scope ('in full or for named line items'). It clearly distinguishes from siblings like create_receipt or get_receipt by focusing on refunds.

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 (for refunding an existing receipt) and gives a caution to confirm details with the user. However, it does not explicitly name alternatives or state when not to use it, such as referencing loyverse_create_receipt for new sales.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: cancelled receipts are excluded, the 31-day data availability limit, and the safety cap on receipts read (max_receipts). It also clarifies that 'top' is ignored when grouping by day, which is a behavioral nuance not obvious from the schema. No contradiction with annotations.

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

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

The description is three sentences with zero waste. It front-loads the core purpose, then lists the metrics and breakdown dimensions, then adds the two critical constraints (cancelled receipts excluded, 31-day limit). Every sentence earns its place and the structure is easy to scan.

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 aggregation tool with 100% schema coverage and no output schema, the description covers the essential context: what it aggregates, what metrics it returns, what grouping options exist, and the data availability limitation. The only minor gap is that it doesn't describe the exact output shape, but since there's no output schema and the description lists the metrics, this is acceptable. The 31-day limitation is a valuable completeness addition.

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 6 parameters. The description adds some context around the 'top' parameter behavior (ignored when grouping by day) and the max_receipts safety cap, but it doesn't add significant meaning beyond the schema. Baseline 3 is appropriate since 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 clearly states the tool aggregates receipts over a date range into totals and a breakdown, with a specific verb ('Aggregate') and resource ('receipts'). It distinguishes itself from raw receipt listing by explicitly saying 'without the model having to page through raw receipts', and lists the exact metrics and grouping dimensions. This differentiates it from siblings like loyverse_list_receipts and loyverse_get_receipt.

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

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

The description implies when to use this tool: when the model needs sales totals/breakdowns rather than raw receipts, explicitly contrasting with paging through raw receipts. It also provides a critical usage constraint: without the Unlimited Sales History add-on, only the last 31 days are available. However, it doesn't explicitly name alternative tools or state when not to use it, so it falls just short of a 5.

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

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

Annotations already mark this as destructive/read-write; the description adds concrete consequence semantics with 'sending 5 leaves 5 in stock regardless of what was there before.' It stops short of mentioning permissions or rollback, but the core overwrite behavior is clearly disclosed.

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

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

Two sentences with no filler; the absolute-value semantics are stated first, then the cross-reference to the read tool. Every sentence earns its place.

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

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

For a simple one-top-level-parameter write with no output schema, the description covers action, scope, parameter semantics, and the safe workflow for delta adjustments. Multi-variant behavior is implied but not explicitly atomic; that 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?

With 0% schema description coverage, the description compensates by explaining the crucial stock_after parameter as an absolute target rather than a delta, and clarifies the payload can cover one or more variants/stores. variant_id and store_id are left to their self-explanatory names, but the main semantic trap is resolved.

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 action precisely: 'Set stock to an absolute figure for one or more variants at a store.' The 'not a delta' clarification makes it easy to distinguish from any inventory-adjustment or read 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?

Gives explicit direction to call loyverse_get_inventory first when the intent is to add or remove a quantity, which is a clear when-to-use rule versus the sibling read tool.

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

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

The description says 'replacing any existing one', which is a destructive overwrite behavior, while the annotations declare destructiveHint=false. This is a direct contradiction: an agent relying on the annotation might assume existing images are not overwritten. The description contradicts the structured metadata.

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

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

A single sentence with no fluff. The action, target, input source, and side effect are all present and front-loaded. Every word earns its place.

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

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

For a simple setter with two required parameters, the description covers what it does and the replacement behavior. It lacks an explicit return-value statement (no output schema), but this is a minor gap. The contradictory annotation slightly reduces the overall completeness, but the description itself is nearly sufficient.

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 50% (only image_url is described). The description maps item_id to 'catalogue item' and image_url to 'public URL', but it does not add detail beyond what the schema already provides. The baseline of 3 is appropriate since the schema covers half the parameters and the description adds minimal new meaning.

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

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

The description states a specific verb ('Attach') and resource ('image to a catalogue item'), and the phrase 'replacing any existing one' clearly communicates the operation's scope. It uniquely identifies this tool among siblings, none of which focus on setting item images.

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

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

The description gives clear context: use this tool to attach an image from a public URL, implying it is not for local file uploads. It does not explicitly name alternative tools or exclusions, but for this simple operation the context is sufficient.

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 carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), lowering the bar. The description adds genuine context by disclosing the dual behavior — id triggers rename, absence triggers create — but leaves edge cases unaddressed, such as whether color can also be updated alongside a rename and what happens to items already linked to a renamed category.

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 11-word sentence that front-loads the primary action ('Create a category') before the alternative rename mode. Every word earns its place, with no filler, restatement of the title, or schema duplication.

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 3-parameter tool with no output schema and no nesting, the description adequately covers the two core operations an agent needs to call it. It falls short on the color parameter's semantics, whether color updates are possible in rename mode, and what the operation returns, though the tool's simplicity keeps these gaps moderate.

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 only 33% (only id has a description), so the description must compensate, and it partially does: 'rename one by passing its id' clarifies that id selects an existing category and that name is the replacement value. However, color has no description in either the schema or the tool description, leaving its role and whether it combines with id entirely to inference from the enum.

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

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

The description uses specific verbs bound to a specific resource: 'Create a category, or rename one by passing its id.' It crisply conveys the two upsert modes, which is exactly the detail an agent needs to tell this from loyverse_list_categories (reading) and from the other loyverse_upsert_* siblings (different entities), even without naming them.

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: call this to create a new category or rename an existing one, with id presence selecting the mode. The description never names alternatives or exclusions — it does not point to loyverse_list_categories for reading or loyverse_delete for removal — so an agent must infer the routing decision from the verb and resource.

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

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

The description adds a valuable privacy warning about writing personal data, which goes beyond annotations. It also clarifies the create/update distinction. However, it does not disclose whether updates are partial or full replacements, which is a significant behavioral gap.

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

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

Two sentences with no filler, front-loading the core purpose and including a crucial privacy caveat. Each sentence earns its place.

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

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

For a tool with 11 parameters and no output schema, the description is under-specified. It lacks details on update behavior, required field validation, and return values, and does not guide the agent on partial updates or idempotency beyond what annotations provide.

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 only 27%, so the description must compensate for the many undocumented parameters. It only mentions 'id' and provides no additional meaning for the other 10 parameters, leaving agents to guess at semantics for fields like city, note, or region.

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

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

The description clearly states the tool creates or updates a customer, with an explicit mention of using the id for updates. It differentiates from sibling tools like get_customer or list_customers by focusing on the upsert action.

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 (when you need to create or update a customer) but provides no explicit guidance on when not to use it or which alternative tools to use for read-only operations. The privacy note adds a usage constraint but doesn't address tool selection.

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 cover read-only behavior (readOnlyHint=false), idempotency, and non-destructiveness, and the description does not contradict them. The description does add the behavioral distinction between create and update based on id presence. However, it does not disclose side effects like partial overwrite behavior or response shape beyond annotation coverage.

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

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

The description is one short, front-loaded sentence with no filler or repetition. It directly conveys the essential create/update behavior without wasting tokens.

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 upsert tool with no output schema, the description is too sparse. It does not clarify required-value relationships (e.g., which amount/percent fields align with each type), what stores means, or what happens on an update when fields are omitted. The annotations provide some safety context, but the description alone leaves several important usage 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 only 43%, with name, type, stores, and restricted_access lacking full schema descriptions. The description only reinforces the id semantics ('passing its id') already present in the schema's 'Omit to create' note. It does not compensate for the undocumented parameters or explain how type, discount_amount, and discount_percent interact.

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 operation: 'Create a discount, or update one by passing its name' and names the target resource. It distinguishes this from the sibling list/get/upsert tools by specifying the discount resource and the create/update behavior. There is no ambiguity about the tool's core purpose.

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

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

The description gives an actionable rule: create by omitting the id, update by passing the id. It does not explicitly mention alternatives or exclusions, such as using list_discounts to retrieve existing IDs before updating. The create/update condition is clear, but sibling comparison guidance is absent.

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 cover the safety profile (non-read-only, non-destructive, idempotent). The description adds the fact that Loyverse uses POST for both create and update尚 and clarifies the stock boundary. It does not disclose response behavior, permissions, or rate limits, but the annotation coverage lowers the burden.

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 with no filler. The core action is front-loaded, the id-based update behavior is stated, and the stock limitation is placed with its alternative action. Every sentence adds value.

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

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

This is a complex 19-parameter tool with no output schema and low schema coverage. The description only addresses id and stock, but does not explain required create/update distinctions, variant requirements, or the meaning of key nested structures. For an agent to call this correctly, significantly more guidance is needed.

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

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

Schema description coverage is only 26%, so the description needed to compensate for the many undocumented parameters. It only clarifies the role of 'id' and notes that stock cannot be set, while 19 parameters exist and many important fields like tax_ids, components, option names, and per-store variants remain unexplained.

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 exactly what the tool does: 'Create a catalogue item, or update one by passing its id.' It clearly distinguishes the action from stock-related tools and is scoped to the item resource, which differentiates it from sibling tools like loyverse_upsert_variant or loyverse_set_inventory.

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 explicit usage guidance: stock cannot be set here, so create the item first and then call loyverse_set_inventory. This both states when not to use the tool and names the correct alternative, leaving little 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 this is a write operation (readOnlyHint false) and idempotent, but the description does not clarify update semantics—whether options are replaced or merged, or what happens to existing data. This is a significant gap for an upsert 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 concise sentence with the primary action front-loaded. No wasted words, and the create/update distinction is immediately clear.

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 five parameters and nested options, this description is too sparse. It omits how updates affect existing modifier_options and doesn't clarify required fields beyond what the schema shows. The lack of output schema means it should at least hint at response behavior, but it doesn't.

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 only 40%, and the description adds no parameter-specific meaning beyond the id behavior already in the schema. It does not explain name, position, stores, or modifier_options, leaving agents without necessary context for those parameters.

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

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

The description clearly states the action: create a modifier group with options, or update by id. It distinguishes from sibling tools (e.g., list_modifiers) by naming the upsert behavior and the resource type.

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

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

It explicitly says to omit id for create and pass id for update, giving clear usage context. It doesn't mention alternatives, but there is no other upsert tool for modifiers, so this is sufficient.

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=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds the create-vs-update behavior (omit id to create, pass id to rename), which is useful. It does not disclose side effects like whether renaming affects existing receipts or whether store_id is required on update, but the annotations cover the safety profile.

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

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

One sentence, front-loaded with the action and resource, and the create/update distinction is packed efficiently. No wasted words.

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 3-parameter upsert with no output schema, the description covers the essential create/update semantics. However, it doesn't mention what the response contains, whether store_id is needed for rename, or any constraints (e.g., unique names). The annotations cover idempotency and non-destructiveness, so the core 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 only 33% (only 'id' has a description: 'Omit to create.'). The description adds meaning for id (create vs update) and clarifies that name and store_id are the core fields, but it does not explain what store_id represents or whether name is a rename target. With low coverage, the description partially compensates but leaves gaps.

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

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

The description states a specific verb ('Register'/'rename') and resource ('till device against a store'), and distinguishes the two modes of operation (create vs update by id). It is clear, though it doesn't explicitly differentiate from sibling upsert tools beyond the resource type.

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: to register a new device or rename an existing one by id. It does not explicitly state when not to use it or name alternatives, but the create/update distinction is clear enough for an agent to select it over list/get tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the create-vs-update behavior, but does not disclose details like response shape, whether omitted fields are overwritten, or any validation rules.

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

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

The description is a single well-structured sentence that front-loads the main behavior and avoids filler. Every word adds 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 13-parameter mutation tool with no output schema and very low schema description coverage, the description is too thin. It does not clarify required fields on update, return value, or how the upsert behaves, leaving important context for an agent to invoke it correctly.

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

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

Schema description coverage is only 15%, leaving most of the 13 parameters undocumented. The tool description mentions only the id's role in updating, and that information largely repeats the schema's own 'Omit to create' description, so it does not compensate for the large coverage gap.

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 operation and resource: create a supplier or update one by passing its id. It conveys the upsert semantics and distinguishes the tool from read-only supplier siblings like loyverse_get_supplier and loyverse_list_suppliers, though it does not name alternatives 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 description gives clear usage context: call it when creating a supplier or updating an existing supplier via its id. It does not provide explicit exclusions or compare against alternative tools, but the create-vs-update condition is understandable without extra 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=false, destructiveHint=false, and idempotentHint=true, so the description is not responsible for those. It adds the create-vs-update behavior based on id, which is useful. However, it does not disclose what happens on update (full replace vs merge) or how missing IDs are handled, leaving some behavioral ambiguity.

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

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

A single sentence that is front-loaded with the action and resource, with no filler. Every word 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 5 parameters, 3 required, no output schema, and low schema coverage, the description is thin. It does not address how to obtain existing tax IDs (e.g., via list_taxes), what happens when an ID is invalid, or constraints on rate/type beyond the schema enum. An agent may be uncertain about edge cases.

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 only 40% (id and rate have descriptions). The description clarifies the id parameter's role (omit to create, pass to update) but does not add meaning for name, type, or stores. It partially compensates for low coverage but leaves the other parameters dependent on the schema's limited info.

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

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

The description states the verb (create/update) and resource (tax rate) explicitly, and distinguishes the two modes via the id parameter. It clearly separates this tool from the read-only list_taxes and other upsert 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 purpose implies when to use it (creating or updating a tax), but it does not explicitly state when not to use it, mention alternatives like list_taxes for finding existing IDs, or note any prerequisites. Usage guidance is implied rather than explicit.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description reveals partial-update semantics: variant fields can be changed without rewriting the item. It does not disclose response/return behavior, but with annotations covering safety and idempotency this is a manageable gap.

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

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

Two sentences, front-loaded with the verb and resource, with no filler. The price-change use case earns its place as the most important practical guidance.

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

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

For a 12-parameter upsert tool with no output schema, this is too spare. It explains the high-level create/update behavior but leaves the relationship among cost, purchase_cost, default_price, stores[].price, and option values unexplained, so an agent is likely to misuse parameters.

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 only 17%; the description compensates minimally by explaining that variant_id selects an update and that price changes are the target use case. The other 10 parameters (sku, stores, options, pricing types, costs) get no semantic guidance.

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 and resource: create or update a variant on an existing item. It also differentiates from related upsert tools by noting that price changes can be done without rewriting the whole item.

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 a clear use case: use this to change a price without rewriting the whole item, which implicitly points to loyverse_upsert_item as the alternative. It lacks explicit when-not-to-use or exclusion conditions, so it stops short of a 5.

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