Cliento MCP by usefulapi

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

The description adds two facts not present in the annotations: the products:read permission requirement and the 'preview API may change without a version bump' stability warning. 'Read-only' merely restates readOnlyHint=true, but the auth scope and volatility disclaimer are genuine additions.

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 clauses, front-loaded with the 'Preview API' caveat and the core resource. Every clause carries information; the only redundancy is 'Read-only', which duplicates the annotation.

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 usefully sketches the return ('one item and its pack balances') and states the auth scope. But for a tool whose two required parameters have zero schema documentation, it leaves an agent without the identifier semantics needed to construct a correct call.

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 both required parameters (locationId, colourBarItemId) rely entirely on the description for meaning, and the description mentions neither. It gives no indication of the loc_/cbi_ identifier formats, where to obtain the IDs, or whether location scoping affects results.

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-ish operation (retrieve one colour-bar stock item) with scope detail: 'and its pack balances; no personal recipes or mixes.' That scope boundary distinguishes it from the broader list/range siblings, though it never names an alternative explicitly.

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

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

'Requires products:read' gives the prerequisite and the 'no personal recipes or mixes' clause signals what this endpoint will not return, which is real routing guidance. It stops short of naming when to call this versus cliento_list_colour_bar_items or cliento_get_colour_bar_range.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the description's added value is the stability warning ('Preview API... may change without a version bump') and the required scope 'products:read' — both real behavioral context an agent needs before building on it. It does not describe failure modes, but the substantive extras clear the bar beyond 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 compact sentence with the preview-status warning front-loaded and no filler. The semicolon-packed phrasing is dense but every 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?

With no output schema and zero parameter documentation, the description should say at least roughly what a returned range contains or how the IDs relate to a location. It covers safety, auth scope and stability well, but leaves the parameters and return shape entirely to inference.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions locationId or colourBarRangeId. The only guidance comes from schema patterns (loc_, cbr_), leaving the description adding nothing about required 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?

States it returns 'One supplier range and its catalog settings', which implicitly conveys a single-resource fetch distinct from the sibling list_colour_bar_ranges. It does not use an explicit verb like 'get/retrieve' or name a sibling, but the singular scope plus the exclusion of 'personal recipes or colour mixes' makes the target resource identifiable.

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 a precondition ('Requires products:read') and a scoping rule (supplier ranges only, not personal recipes/colour mixes), but never states when to call this versus cliento_list_colour_bar_ranges or cliento_get_colour_bar_item. Usage is inferable from the singular/plural naming 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new context the annotations cannot express: this is a Preview API that may change without a version bump, a real stability caveat for an agent deciding whether to depend on it.

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 preview/stability warning front-loaded, then the payload contents. No filler, nothing repeated from annotations or schema.

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

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

For a single-parameter read tool with full annotations and no output schema, the description supplies what's needed: the returned fields and the API stability warning. The only missing piece is guidance on where the locationId comes from.

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

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

Only one parameter exists, and schema description coverage is 0% – the locationId is documented nowhere in prose. The description says nothing about the identifier's origin or its 'loc_' prefix format, so it fails to compensate for the schema gap even though the schema does carry a pattern constraint.

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 location") and enumerates the returned fields (name, currency, time zone). It is clearly distinguishable from cliento_list_locations by singularity, though it never names that sibling explicitly.

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

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

Singular vs. plural only implies the retrieve-by-id use case; the description never says when to prefer this over cliento_list_locations or how to obtain a locationId. Useful but the routing 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds real context beyond that: required auth scopes, the conditional nature of the stock balance ('when tracked'), cost field gating, and the preview-stability warning that responses may change without a version bump. Return shape beyond these hints is not described.

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 tight, single-sentence-style block with no filler, and the core purpose ('One product and its current stock balance') leads. The 'Preview API:' prefix is slightly front-loaded noise before the purpose, but it is relevant stability 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?

With no output schema, the description does well to identify what comes back (product, stock balance, cost fields) and what auth and stability to expect. It is incomplete on the two required parameters, which are undocumented in both the schema and the description for a tool that is location-scoped.

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% for both productId and locationId, so the description would need to compensate. It says nothing about what either parameter means or that locationId determines which stock balance is returned, leaving an agent to infer the per-location scoping.

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 ('One product and its current stock balance, when tracked') makes the single-item scope clear against the list_products sibling. It does not explicitly name the sibling or note that a locationId is required to scope the fetch, which keeps it short of a 5.

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

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

The description gives prerequisites (requires products:read, stock:cost for cost fields) but never states when to use this versus cliento_list_products or cliento_list_stock_movements. Usage is only implied by 'One product'.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered structurally. The description earns credit for disclosing two things the annotations cannot: the required scope and the preview/unstable-contract warning ('may change without a version bump'), which is meaningful operational context.

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

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

Three short sentences, front-loaded with the core purpose and followed by the prerequisite and the stability caveat. Every sentence carries information; no filler or 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 simple two-parameter read operation with full annotation coverage and no output schema, the description covers purpose, scope, permission, and API stability. What is missing is any clarification of what a 'resource' is (staff, room, bookable item) and how the two IDs relate, which would fully close 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 0%, so the description carries the full burden for two required parameters, yet it says nothing about locationId or resourceId beyond their implicit presence. The schema's loc_/res_ prefix patterns are the only hint at format, and the description does not compensate for that gap or explain scoping behavior.

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

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

States a specific verb+resource combination: fetches a single resource with its status and online-booking settings, which clearly distinguishes it from the sibling list_resources / list_resource_groups operations. It does not explicitly name the sibling it contrasts with, so it falls short of the top mark.

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 access prerequisite (requires resources:read) which helps gate usage, but it never states when to prefer this over cliento_list_resources or when it should not be used (e.g., bulk retrieval). Usage is only implied by the singular 'one resource' phrasing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the description doesn't need to re-state safety. What it adds is genuinely beyond annotations: the required services:read scope, the stability warning that the API may change without a version bump, and the notable exclusion of free-text descriptions from the payload.

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

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

Two compact sentences, front-loaded with the 'Preview API' caveat and the core resource, with no filler. The 'excluding free-text descriptions' clause earns its place by preventing wrong expectations about the payload.

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

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

For a read-only single-resource fetch with no output schema, the description tells the agent what is returned in broad terms but not the shape of the service object or its overrides, and gives no hint about error behavior for unknown IDs. 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 0% for two required parameters, so the description carries some burden. It never explains locationId or serviceId semantics, though the schema's own patterns (^svc_ .*, ^loc_ .*) make the ID formats self-evident. Marginal added value.

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

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

The description states a specific resource ('One service and its per-resource overrides') and a meaningful scope qualifier ('excluding free-text descriptions'), which is clearly distinct from the sibling cliento_list_services. It doesn't name the sibling explicitly, but the singular-vs-list distinction is obvious.

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

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

Usage is only implied: the required services:read scope and the 'Preview API' framing signal preconditions, but there is no explicit when-to-use statement or pointer to alternatives like cliento_list_services or cliento_list_resource_services. An agent can infer 'fetch a single service by id' but must reason about 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: it is a preview API that may change without a version bump, it requires the products:read scope, and it excludes recipe/mix data. These are traits an agent cannot get from the annotations or schema.

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

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

Three compact clauses with the capability first, then the filter constraint, then permission/preview caveats — well front-loaded and free of padding. It is terse to the point of being telegraphic, which slightly hurts readability but not efficiency.

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

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

With no output schema, the description does list the returned content (catalog, barcodes, pack balances), which is helpful. But for a 6-parameter tool with 17% schema coverage, it omits the meaning of the required locationId and the limit/pagination interplay, so it is not fully sufficient to call the tool confidently.

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

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

Schema description coverage is only 17% (only 'after' is documented), so the description must compensate. It does clarify the mutual exclusivity of rangeId, ean and articleNumber, which the schema does not encode, but leaves locationId (required), limit, and the semantics of the colour-bar item fields 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 names the payload ('Shade/item catalog, barcodes and pack balances') and the title supplies the verb ('List colour bar items'), but the description itself never states the action or resource explicitly and reads like a category label. An agent must combine name + title + description to infer that this lists colour bar items for a location.

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?

'Choose at most one of rangeId, ean or articleNumber' gives a hard usage constraint, and 'no recipe or mix data' rules out one expected use. However, there is no guidance on when to pick this over sibling tools such as cliento_get_colour_bar_item or cliento_list_colour_bar_ranges, so alternative selection 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, and the description adds genuinely new operational context: it is a Preview API that may change without a version bump, and it requires the products:read scope. That auth/stability information is exactly the kind of thing annotations cannot express. It still omits pagination/return-shape behavior.

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

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

Very compact, with each clause carrying distinct information (preview status, data scope, auth scope, stability). It is under-front-loaded, though: it leads with API status rather than stating what the tool returns, so the core purpose arrives only implicitly.

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 three-parameter list tool with no output schema, the description covers auth, scope and stability but leaves the listing semantics unaddressed — pagination via cursor, default page size, and the required locationId scoping. Those are the gaps an agent actually needs to call it correctly, though the safety profile is adequately carried by annotations.

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

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

Schema coverage is only 33%: 'after' is described in the schema but 'limit' and 'locationId' are undocumented. The description says nothing about any parameter — notably it never explains that locationId is required and effectively scopes the whole listing, nor what limit defaults/bounds are. With low coverage, the description should compensate and does not.

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 identifies the data domain (supplier range catalog, pack-size and list-price settings) and excludes adjacent data (no personal recipes or colour mixes), but it never states the actual verb/resource pairing implied by the name — returning a paginated list of colour bar ranges. Siblings cliento_list_colour_bar_items and cliento_get_colour_bar_range are not distinguished, so an agent must infer the difference from the name alone.

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

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

'no personal recipes or colour mixes' gives a scope exclusion, which is a useful boundary, but there is no statement of when to call this versus the sibling list/get colour bar tools and no prerequisite flow (e.g., obtain locationId from cliento_list_locations first). Usage must be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description earns credit for disclosing something structured fields do not: this is a Preview API whose surface may change without a version bump, which is a real risk signal 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?

Two short clauses with zero waste: the resource and returned fields come first, and the volatility warning is compactly appended. Nothing is redundant or buried.

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

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

With no output schema, the description carries the return-value burden and does so at a high level by enumerating key fields. It does not say whether the result is a flat list or paginated, nor how many locations to expect, leaving a small gap for a zero-parameter list 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?

There are zero parameters, so the baseline is 4. The description adds value by naming the fields an agent can expect (name, currency, time zone) rather than merely repeating a schema.

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

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

States the resource (locations accessible to this API key) and the fields returned (name, currency, time zone), which clearly separates it from the singular sibling cliento_get_location. It stops short of naming the sibling or saying 'list' explicitly, so it is clear but not maximally differentiated.

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

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

Usage is only implied: the plural resource plus the 'accessible to this API key' scope suggests a discovery call before calling cliento_get_location. There is no explicit when-to-use guidance or exclusion, and the 17 siblings are not referenced.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive behavior, so the description does not need to repeat that. It does add genuinely useful context: the API is a preview that may change without a version bump, and the response excludes payment or gift-card data. This goes meaningfully beyond the structured fields.

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 the preview/instability caveat and data-scope exclusion front-loaded. Nothing is padded, though the phrase 'with optional company registration numbers' is slightly ambiguous about whether they are returned or filterable.

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?

One required parameter and no output schema keep the burden moderate, and annotations cover the safety profile. However, the description never explains the locationId input or what the merchant list contains beyond a broad scope note, leaving gaps for an agent deciding how to call it.

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

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

Schema description coverage is 0%, and the only parameter (locationId) is documented only by the schema's pattern constraints. The description says 'at the location' but provides no format, expected prefix, or sourcing guidance for locationId, so it does not 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 the resource returned (legal sellers at a location, with optional company registration numbers), which is a specific enough purpose to distinguish it from sibling list tools such as cliento_list_locations or cliento_list_products. It does not name a sibling, but the resource itself is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisite beyond the required locationId, and no exclusions other than the data-scope note about payment/gift-card data. 'Preview API' signals instability but not usage conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, and the description adds real context beyond them: required products:read scope, gated cost fields under stock:cost, the meaning of omitted balances (product not stock-tracked), and a preview-API stability warning. Only pagination/return-shape behavior is left unmentioned, which the after cursor in the schema partly covers.

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

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

Three tight sentences with no filler, and the resource identification comes first. The telegraphic fragments ("Cost fields appear only with stock:cost") are dense but still readable.

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?

Behavioral and permission context is solid for a read-only listing, but with five parameters at 20% schema coverage, an agent still cannot tell what the parameters do or what shape the returned product/balance records take. For a tool with no output schema, that leaves meaningful 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 20%, so the description needs to carry parameter meaning, and it does not: nothing explains locationId (the sole required parameter), the ean/articleNumber filters, or how limit/after paginate. The one implicit hint is that balances are current, suggesting location scope, but that is not spelled out.

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: product catalog plus current stock balances, with an explicit note that cost fields depend on the stock:cost scope. It is clearly a read-oriented listing of products, though it never names how it differs from cliento_get_product or cliento_list_stock_movements.

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

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

There is no guidance on when to use this versus the sibling get_product or list_stock_movements tools, and no stated conditions for choosing between them. The only conditions given (products:read required, cost fields need stock:cost) are permission facts 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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it is a Preview API that may change without a version bump, and it requires resources:read. It doesn't describe pagination behavior, but the preview instability warning is a real value-add.

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 clauses, front-loaded with the preview caveat and the read-only scope. No filler; every phrase carries information, though the core purpose statement is a bit cryptic.

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 3-param read-only list tool with no output schema, the preview-status and scope warnings are helpful, but the description never defines what a 'resource group' is or how it relates to resources, leaving the agent to guess at the returned entity.

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%: 'after' and 'limit' have schema descriptions, but 'locationId' (the sole required param) is undocumented in both schema and description. The description adds no meaning about any parameter, so it doesn't compensate for the 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 gives a concrete verb-ish phrase ('Resource headings in display order') but never plainly says it lists resource groups, and doesn't distinguish it from close siblings like cliento_list_resources or cliento_list_service_groups. An agent must infer that 'resource groups' are the 'headings' being returned.

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

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

It states the required scope (resources:read), which is useful prerequisite info, but gives no guidance on when to pick this over cliento_list_resources or cliento_list_service_groups. No alternatives or exclusions are named.

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 read-only, idempotent, non-destructive, and open-world behavior. The description adds meaningful context beyond those annotations: it requires 'resources:read' and warns that the Preview API may change without a version bump, which is useful operational detail.

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-loads the preview status and catalog scope. It is mostly efficient, though the read-only statement repeats the annotation and the sentence packs several distinct facts into one long clause.

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 purpose, scope exclusions, authorization, and API stability, which is helpful for a list tool with no output schema. It is still incomplete for a required location-scoped list operation because it does not explain locationId, limit, or cursor 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?

With only 33% schema description coverage, the description should explain the required locationId and the pagination or limit behavior. It provides no parameter guidance at all, leaving the agent dependent on sparse schema constraints for locationId and an undescribed limit parameter.

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

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

The description identifies the resource domain as a bookable resource catalog and online-booking settings, with the explicit exclusion of bookings and availability. This gives a clear sense of what the tool returns, though it does not explicitly name sibling alternatives such as resource groups or individual resource retrieval.

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 'no bookings or availability' implies when not to use this tool, and the catalog/settings scope implies when it is appropriate. However, it does not name alternative tools like cliento_get_resource or cliento_list_resource_groups, so the agent must infer the routing decision.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safe-read profile is covered; the description adds genuinely new context by naming the required scope (services:read) and warning that this is a preview API that may change without a version bump. It doesn't discuss pagination behavior, though the schema covers the cursor parameter.

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

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

Two compact sentences with no filler; the payload description and the auth/preview caveats are front-loaded. Phrasing is slightly awkward ('Services as this resource offers them') but not wasteful.

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 describing the returned fields is helpful, and the preview/scope caveats are welcome. However, for a 4-parameter tool with low schema coverage, the description never explains the required location/resource scoping or pagination, leaving an agent to guess at call-correctness 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 25% – locationId and resourceId have no descriptions at all – and the description does not compensate by explaining that these are required scoping identifiers or what the limit/after pagination means. Only the 'after' parameter carries schema documentation, leaving the two required parameters semantically bare.

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 ('Services as this resource offers them') and enumerates the returned attributes (duration, price, override settings), which distinguishes it from the sibling cliento_list_services that presumably lists all services. The verb is softened to 'Preview', but the intent is clear 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?

No explicit when-to-use guidance and no mention of when to prefer this over cliento_list_services or cliento_get_service. The agent must infer from the name that this is the per-resource variant rather than a global service listing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, yet the description still adds real value: the API is a preview surface that may change without a version bump, and it names the required OAuth scope. Both facts go beyond annotations and affect whether an agent should depend on the response.

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

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

Two short sentences, front-loaded with the most decision-relevant fact ("Preview API") and the auth requirement. Nearly every clause earns its place; the fragment "their add-on marker" is terse to the point of being cryptic but costs little space.

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 3-param read tool with no output schema, the description covers stability and auth but omits pagination behavior despite the presence of limit/after, and never defines what a service group or "add-on marker" actually is. An agent can fire the call but cannot reason about the results or pagination strategy.

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%: locationId (required) and limit are completely undocumented in the schema, and the description says nothing about any of the three parameters. Worse, the one documented param (after) carries boilerplate text about stock movements that is misleading in this context, so nothing compensates for the 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 names the returned resource ("Service headings and their add-on marker"), which tells an agent roughly what data comes back, but it never states a verb and gives no clue how a "service group" differs from the sibling list_services or list_resource_services. The agent must infer that this is a list operation over some grouping layer.

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 one concrete usability constraint — "Requires services:read" — which is genuinely helpful pre-call context, but it offers no when-to-use/when-not guidance and never routes the agent away from the many sibling list_* tools. Selection must be inferred from the name alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so credit goes to the extra disclosures: the API is a preview that may change without a version bump, requires services:read authorization, and deliberately strips free-text descriptions from results. That is real behavioral context an agent cannot get from 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 dense sentence-cluster with no filler: return payload first, then omissions, then permission, then stability. Every clause carries distinct 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 permissions, payload shape, and stability, but for a 4-parameter list tool with 25% schema coverage and no output schema, it leaves pagination behavior and the resourceId filter under-explained. Adequate but with clear gaps.

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

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

Schema coverage is only 25% (just 'after' documented), so the description should compensate. It hints at resourceId semantics via 'per-resource overrides' but never explains that resourceId scopes the catalog, nor clarifies limit defaults or that 'after' is the pagination cursor for this endpoint (the schema text oddly references stock movements).

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

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

Names the resource (service catalog) and enumerates the returned data precisely: durations, prices, VAT, per-resource overrides, and explicitly what is omitted (free-text descriptions). It does not distinguish itself from nearby siblings such as list_resource_services or list_service_groups, so an agent must infer that this is the full-catalog variant.

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 context given is the required 'services:read' scope and the 'Preview API' framing; there is no statement of when to choose this over list_resource_services or list_service_groups, nor when resourceId filtering is appropriate. The agent gets a prerequisite but no routing 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 declare readOnly, idempotent and non-destructive, so the description earns credit for adding context annotations cannot: it discloses that PIN settings and secrets are omitted (a data-scoping guarantee), that staff:read is required (auth scope), and that the API is preview and 'may change without a version bump' (stability caveat). It stops short of describing pagination or result volume.

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

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

Three compact sentences, front-loaded with the 'Preview API' caveat and the returned fields. Slightly telegraphic ('optional names') but no sentence is wasted.

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

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

For a simple one-parameter read with no output schema, the description covers the important non-obvious parts (omitted secrets, auth scope, preview instability). It still leaves gaps around pagination, result ordering, and the meaning of the location scoping that an agent needs to use the tool confidently.

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

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

Schema description coverage is 0% for the single required locationId, and the description says nothing about it. It never explains that staff are scoped to a location or what the loc_ prefixed identifier refers to, leaving the agent to infer the scoping model from the schema pattern 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?

The description names the resource and enumerates what is returned (staff IDs, names, linked resource IDs), which goes beyond restating the title 'List staff'. It is not fully distinguished from siblings like cliento_list_resources, which in many systems overlap with staff, so an agent could hesitate between the two.

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?

'Requires staff:read' communicates a prerequisite, implying this is the read path for staff data. However, there is no explicit statement of when to prefer this over cliento_list_resources or cliento_get_resource, and no exclusions or pagination 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 read-only, idempotent and non-destructive, yet the description adds several non-obvious traits: eventual consistency ('movements may appear about ten seconds after creation'), the required stock:read scope, the specific fields omitted from responses, and API instability without a version bump. These are exactly the behaviors an agent cannot infer from structured fields.

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, front-loaded with the data scope before the caveats, with no filler. It is packed slightly tight – the omission list and caveats share one sentence – but nothing is wasted.

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

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

No output schema exists, so the description usefully sketches the return shape (field omissions, ordering, latency) and access requirements. However, it leaves the filtering parameters and the mandatory locationId unexplained, which is a meaningful gap for a six-parameter list tool.

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

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

Schema description coverage is only 17% – just the 'after' cursor is documented. The description explains none of the six parameters: it never mentions the required locationId, what the `type` filter accepts, the default/max of `limit`, or how productId vs colourBarItemId narrow results. With such low coverage the description had real room to compensate and does not.

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 the specific resource (stock changes) and its ordering (oldest first), plus which fields are omitted, so an agent knows exactly what data comes back. The verb is only implied ('Stock changes') rather than stated as a list operation, and the required locationId scope is not mentioned. Sibling confusion is unlikely since all siblings target other resources.

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

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

It states a prerequisite ('Requires stock:read') and that this is a preview API that may change, but gives no explicit when-to-use/when-not or alternative tool routing. Usage is only implied by the resource name, which is adequate but thin.

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