Zettle MCP by usefulapi

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

Goes beyond the annotations by explaining the concrete consequence of non-idempotency ('calling twice creates two products'), naming required scopes (READ:PRODUCT / WRITE:PRODUCT), and disclosing a merchant-configuration validation rule for vat_percentage. The endpoint is included; only side effects on inventory or error modes are left unaddressed.

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?

Roughly five terse clauses, each carrying distinct load (mutation type, destination, idempotency, auth, validation constraint, price units, route), with the most decision-relevant facts front-loaded.

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 4-parameter create tool with no output schema and no annotations on auth, the description covers safety, idempotency, permissions, and validation adequately. The one gap is not saying what the successful response yields (e.g., the new product's id), which an agent must know to chain follow-up calls.

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 field-level meaning is already carried by the schema. The description reinforces the VAT-rate constraint and smallest-currency-unit prices, but adds no information about the nested variants structure beyond what the schema documents, so baseline 3 applies.

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

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

States a specific verb and resource ('add a new product to the Zettle product library') and clarifies the downstream effect (appears in POS and online store). This clearly separates it from the read-only siblings like zettle_get_product and zettle_list_products.

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 'WRITE:' prefix plus the creation framing make the when-to-use condition evident, and the non-idempotent warning steers against blind retries. It stops short of explicitly naming the sibling read tools as alternatives, but the create-vs-fetch distinction is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, and non-destructive behavior. The description adds useful context by tying the result to an API key and naming the endpoint and returned identity fields; it does not cover rate limits or error behavior, but those are minor for this zero-param read.

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: it front-loads what the tool returns and follows with the endpoint. Every element — identity scope, return fields, endpoint — 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 identity endpoint with no output schema, the description is nearly complete: it names the returned fields and the endpoint. It could say more about response shape or auth failure behavior, but that is not essential here.

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

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

There are zero input parameters, so the baseline is 4. The empty schema is appropriate, and the description correctly avoids inventing 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 resource and scope: the Zettle user and organization associated with the API key, including the exact endpoint and key return fields. It is clearly distinguishable from siblings such as account balance, payout info, and transaction listing.

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 — identifying the current API key's account — but there is no explicit when-to-use/when-not guidance and no named alternatives. An agent can infer the use case from the description, but must reason about siblings itself.

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, and the description still adds meaningful non-schema context: the READ:FINANCE scope requirement and the concrete endpoint. It also explains what the returned fields mean (totalBalance in the smallest currency unit, currencyId), which the agent could not infer from the schema alone.

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?

Front-loaded with the resource and the return shape, then the enum semantics, then auth and endpoint — no sentence is filler. The telegraphic fragment style ('Needs READ:FINANCE. GET /v2/...') is terse but every element carries information.

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

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

There is no output schema, so the description must carry the return shape, and it does name totalBalance and currencyId along with units. Auth scope and endpoint are covered; the only remaining gap is guidance on when to pick this over the neighbouring account/payout tools.

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

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

Schema coverage is 100%, so the schema already documents both parameters including the enum. The description restates the LIQUID/PRELIMINARY meanings and the point-in-time option but adds little beyond the schema for the parameters themselves; the 'smallest currency unit' note concerns the response, not inputs.

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

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

States a specific verb+resource ('the merchant's Zettle account balance') and defines the two account variants (LIQUID = available for payout, PRELIMINARY = not yet settled) plus the underlying endpoint. It is clear what the tool returns, but it never names a sibling to contrast with (e.g. zettle_get_account or zettle_get_payout_info), so differentiation is left implicit.

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

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

'Optional point in time' implies the historical-balance use case, but there is no explicit when-to-use or when-to-prefer-another-tool guidance, and the boundary with zettle_get_payout_info / zettle_list_account_transactions is unstated. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description still adds genuine value: the required READ:PRODUCT scope, the underlying endpoint, the returned fields, and the next_offset pagination loop that the agent must continue.

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

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

Two tight sentences, front-loaded with what is returned before the auth and endpoint details. Every clause carries information: contents, return shape, pagination instruction, permission, and route.

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

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

With no output schema, the description correctly compensates by naming the returned fields (products, discounts, next_offset) and the auth scope. The only remaining gap is that it does not clarify how 'library' relates to the other product/inventory listing siblings.

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

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

Schema description coverage is 100%, and both parameters are fully documented in the schema, including the default of 100 and the 1-500 range. The description's pagination hint ('pass it back as offset') duplicates what the offset schema description already says, so it adds no meaning beyond the structured data.

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

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

States a specific resource ('product library') plus the distinguishing scope 'together with its discounts (name, amount or percentage)', which differentiates it from a plain product listing. It does not explicitly name which sibling (e.g. zettle_list_products) it supersedes, so the separation is implied rather than stated.

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

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

Usage context is implied: use this when you need products and their discounts in one paginated call, and the 'pass it back as offset' note gives a concrete pagination pattern. However, it never states when to prefer this over zettle_list_products or zettle_get_product, and there are no exclusions or prerequisites beyond the permission scope.

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 openWorldHint=true, so the safety profile is covered. The description adds real value beyond that with the required auth scope (READ:FINANCE) and the underlying endpoint GET /v2/payout-info. It says nothing about freshness semantics or whether 'periodicity' is fixed vs. configurable, but with annotations carrying the safety burden a 3 is appropriate.

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

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

Two compact fragments with the resource and returned fields front-loaded, then the permission and endpoint. No filler sentences; every element carries information.

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

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

With only one optional parameter, full schema coverage and annotations present, the main remaining gap was return-value shape – and the description compensates by enumerating the five returned fields. The auth scope and endpoint round it out.

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

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

The single 'at' parameter is fully described in the schema (100% coverage), so the description need not repeat it. However, the description could have clarified what as-of dating means for payout figures (e.g., whether historical snapshots are supported), which is the one non-obvious semantic here.

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

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

States a specific verb+resource (payout information of the LIQUID account) and enumerates the fields returned, which implicitly separates it from zettle_get_account_balance and zettle_get_account. It stops short of naming any sibling explicitly, but an agent can still tell what this tool returns.

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

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

There is no statement of when to use this versus zettle_get_account_balance or zettle_list_account_transactions. The only guidance is a permission prerequisite (READ:FINANCE), which is a precondition rather than usage 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 declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them: the required OAuth scope (READ:PRODUCT) and the concrete endpoint path, which tells an agent this is a plain network-backed read against the organization's own product set.

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: the first front-loads what the tool returns, the second packs the auth requirement and endpoint. No filler, no repetition of the title.

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

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

For a one-parameter read with annotations covering the safety profile, nothing needed to invoke it correctly is missing: the identifier, the auth prerequisite, and the shape of the returned record are all stated. No output schema exists, and the description compensates by listing the returned facets.

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

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

Schema description coverage is 100%, so the single product_uuid parameter is already documented in the schema, including its UUID pattern. The description only restates that the lookup is by UUID, adding no format or sourcing guidance beyond the structured field.

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

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

States a specific verb+resource ('One product by UUID') and enumerates exactly what comes back (variants, prices, VAT, category, images, online-store data). This clearly separates it from zettle_list_products, which returns many, without the agent needing to open either schema.

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

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

The 'by UUID' framing and the required READ:PRODUCT scope make the appropriate context clear, and the singular 'One product' implies listing should go through the list sibling. It stops short of naming an explicit alternative or stating what to do when the UUID is unknown.

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 readOnly/openWorld annotations, it discloses the required READ:PURCHASE scope, the underlying endpoint GET /purchase/v2/{purchaseUuid}, and that a deprecated ID form will be rejected. That is exactly the extra context an agent needs before calling.

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 dense front-loaded sentence plus an auth clause and endpoint suffix; every element earns its place. The nested parenthetical is long but carries the critical deprecation warning, so it isn't waste.

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

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

For a one-parameter read tool with no output schema, the description covers input provenance, auth requirement, endpoint, and the shape of the returned data. Nothing needed to call it correctly 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds semantic value by disambiguating purchaseUUID1 from the deprecated short purchaseUUID. It reinforces the format without repeating the UUID example already in the schema.

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

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

States a specific verb and resource: fetch one purchase (sale or refund) in full by purchase UUID, listing the payload contents (line items, VAT, payments, refund links). It is clearly distinguishable from zettle_list_purchases, which it names as the source of the identifier.

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 routes the agent: get the ID from zettle_list_purchases' purchaseUUID1 field, and it warns that the older short purchaseUUID is deprecated and rejected. It doesn't state when-not-to-use beyond that, but the single-purchase vs list split is unambiguous.

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

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

Beyond the readOnly/non-destructive annotations it discloses the READ:PRODUCT permission requirement, the endpoint used (/v3/stock vs /v3/stock/{inventoryUuid}), that untracked products are silently omitted, and that results are paged via next_cursor. These are real operational facts an agent needs and cannot get from 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?

Four short clauses, each carrying distinct information (payload fields, scoping switch, inclusion filter, permission, paging, endpoints), with the core purpose front-loaded. No filler or redundancy.

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

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

With no output schema, the description does the job of naming the returned fields and explains paging, permissions and filtering. It stops short of clarifying what 'balance' includes (available vs reserved) or the page-size default, though the latter is in the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by spelling out the behavioral difference between supplying and omitting inventory_uuid and by tying paging to next_cursor. It adds nothing on limit bounds, but the schema already covers that.

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

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

Specific verb+resource: it returns stock balances per product variant and enumerates the fields (balance, low-stock level/alert, last update). It does not distinguish itself from the close sibling zettle_get_stock_for_products, which an agent could easily confuse with this one.

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 clear scoping rules: with inventory_uuid it returns that single store's inventory, without it returns all stores, and only inventory-tracked products appear. It lacks explicit when-to-use/when-not guidance relative to zettle_get_stock_for_products or list_products, so no exclusions are 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 declare readOnlyHint=true and destructiveHint=false, so 'read-only lookup, nothing is changed' mostly repeats structured data. However, it adds non-obvious behavior the annotations do not cover: the required READ:PRODUCT scope and the cursor rule that the identical product_uuids must be resent to page. The 'POST /v3/...' detail explains why the read-only hint matters but adds little for an agent.

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 ordered by importance: what it returns, the auth prerequisite, then paging. Nothing is padded and no sentence is redundant.

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

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

No output schema exists, so the description should say what a balance record contains or what happens with unknown/inaccessible product UUIDs; it does neither. Security hints and paging are covered, but the return contract is a real gap for a data-fetch tool.

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

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

Schema coverage is 100%, so the parameters are already documented. The description still adds value by pairing cursor with 'send the same product_uuids again', a constraint the schema does not state. limit and the response shape are left entirely to the schema, which is fine.

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

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

States a concrete resource and scope: stock balances for a set of specific products within one inventory. That scope implicitly separates it from zettle_get_stock (single) and zettle_list_products, but no sibling is actually named, so differentiation is left to inference.

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

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

Provides a real prerequisite (READ:PRODUCT) and paging procedure (use next_cursor, resend the same product_uuids). It never explicitly says when to prefer zettle_get_stock instead, but the context that selects this tool is clear from the stated scope.

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?

Goes well beyond the annotations: it discloses the required READ:FINANCE scope, that end is exclusive, that amounts are in the smallest currency unit and may be negative, the returned fields (timestamp, amount, type, originating transaction UUID) and offset-based pagination via next_offset. That is exactly the extra context annotations cannot carry.

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 dense but front-loaded sentence plus short permission, pagination and endpoint notes; the resource and date window lead. The telegraphic style ('Page with next_offset') is efficient but occasionally terse enough to read as shorthand.

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

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

With a full schema, read-only annotations and no output schema, the description still enumerates the response fields and pagination mechanism, and flags the auth requirement. Nothing material for a correct call 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?

Schema coverage is 100% and already documents ranges, defaults and the offset/next_offset pairing, so the description only needs to reinforce. It does add the semantic edge that end is exclusive and that the returned records are paginated, but most parameter detail duplicates the schema.

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

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

States a specific verb and resource (list transactions), names the exact transaction categories covered (payments, fees, payouts, adjustments), the accounts (LIQUID/PRELIMINARY) and the date window. This is clearly distinguishable from siblings like zettle_get_account_balance or zettle_list_purchases.

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: the mention of READ:FINANCE scope and the endpoint signal a finance-reporting context, but it never says when to choose this over zettle_get_account_balance or zettle_get_payout_info, nor any when-not condition.

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 openWorldHint=true. The description adds useful context beyond annotations: the required READ:PRODUCT permission and the underlying HTTP endpoint. It does not cover pagination or rate limits, but the added auth and endpoint details are material.

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

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

The description is compact and front-loaded: purpose first, then return fields, then permission requirement and endpoint. Every piece of information is useful, with 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?

There is no output schema, so the description's mention of uuid and name is valuable return-shape information. The required permission is also included. Pagination or ordering details are absent, but for a simple zero-parameter list operation the description is nearly 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 tool takes zero parameters, so parameter semantics are inherently simple. The description mentions returned fields (uuid, name), which is output context rather than parameter guidance. With no parameters to document, the baseline of 4 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 product categories. It adds the returned fields (uuid, name), making the purpose concrete. It does not explicitly contrast with sibling list operations, but the resource is distinct enough for an agent to select it.

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 by saying it lists categories and requires READ:PRODUCT, but it does not explicitly state when to use this tool versus sibling tools like zettle_list_products. The guidance is adequate but not proactive.

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 openWorldHint=true, so the safety profile is covered. The description adds value beyond them by naming the required auth scope (READ:PRODUCT) and the backing endpoint (GET /v3/inventories), both of which help an agent anticipate failures. Only the pagination/result-size behavior is left unaddressed.

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

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

Two short sentences plus a scope and an endpoint fragment — every clause carries information an agent would otherwise have to guess. The most decision-relevant content (what is returned) is front-loaded, with the cross-reference and permission second.

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

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

There is no output schema, but the description compensates by listing the returned fields and the full type enum, so the agent knows the shape of the response. With annotations covering safety, auth scope named, and the downstream call identified, nothing needed to invoke this correctly 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 takes zero parameters, and the schema correctly has an empty properties object at 100% coverage, so there is nothing to disambiguate. Baseline for a 0-param tool applies, and the description adds the response field list on top.

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

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

The description opens with a specific verb plus resource ("List the stock locations (inventories)") and enumerates exactly what each record carries: inventoryUuid, name, type with all four enum values, and default flag. This distinguishes it unambiguously from siblings like zettle_list_products or zettle_get_stock, whose names alone wouldn't tell an agent which returns location data.

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

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

It gives real routing guidance: "Use the STORE inventoryUuid with zettle_get_stock," which tells the agent this tool is a prerequisite/discovery step for a named sibling. It stops short of stating when NOT to call it or how it relates to the other list-style tools, but the follow-on path is explicit and actionable.

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 readOnly/destructive annotations, it discloses the required READ:PRODUCT scope, that prices are in the smallest currency unit, and that the upstream API returns the full library which this tool paginates. That is real added context; the only gap is no note on rate limits or what an empty result looks like.

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

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

Three dense sentences, front-loaded with the resource and returned fields, then behavioral caveats, then the permission and endpoint. Every clause carries information; nothing is padded.

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

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

There is no output schema, and the description compensates by enumerating the returned fields (variants, SKU, barcode, price, cost price, VAT, category, online status, ETag). Pagination is covered via limit/offset and the reference to next_offset. Minor gap: it doesn't state the response envelope shape.

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 100% schema coverage, the schema already documents limit, offset and name_contains in detail. The description only restates that limit/offset slice and name filters, adding the price-unit caveat rather than parameter-specific meaning. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the products in the POS product library') and enumerates the fields returned, so the scope is unmistakable. It does not explicitly contrast with zettle_get_product or zettle_list_categories, so sibling differentiation is only implied by the 'list' vs 'get' naming.

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?

'Zettle returns the whole library at once; this tool slices it with limit/offset and filters by name' gives clear conditions for use. It never names the alternative for fetching a single product, so the routing guidance is incomplete 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?

Adds real context beyond annotations: required READ:PURCHASE scope, amounts in smallest currency unit, default 3-year window, and the pagination round-trip contract. Annotations already cover read-only safety, so this adds the operational details an agent otherwise couldn't guess.

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 dense sentences with zero filler, ending with the endpoint path. Slightly crowded – auth, unit convention, window default and pagination are all packed into one long run-on – but each clause carries information.

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

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

Covers auth, unit conventions, default time window, pagination loop, and the payload contents, which is what an agent needs to call this correctly without an output schema. Only the ordering default vs. the descending parameter interaction could be stated more explicitly.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by explaining the pagination protocol (pass next_page_hash back as last_purchase_hash with identical other arguments), which the schema alone does not make clear.

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

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

Specific verb + resource (list POS purchases, sales and refunds) plus a concrete enumeration of the fields returned. Clear distinction from the read-one sibling zettle_get_purchase is implied by 'list' vs 'get' and the pagination mention.

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?

States the default window (last 3 years) and the prerequisite scope READ:PURCHASE, but never says when to use this versus zettle_get_purchase or zettle_list_account_transactions. Usage is only implied by the resource it operates on.

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