Tillhub MCP by usefulapi

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: it discloses which fields come back and explicitly notes '(no credentials)', which reassures the agent that secrets are not exposed and pre-empts a common misinterpretation.

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

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

One sentence plus the HTTP endpoint; every clause carries information (subject, returned fields, security caveat, route). 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?

For a parameterless, read-only identity tool with no output schema, the description supplies everything an agent needs: what is returned, identity scoping, the security caveat, and the endpoint. No material gaps remain.

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 of 4 applies. Nothing in the description needs to compensate for schema coverage, and the empty object schema is self-explanatory.

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

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

The description names a specific verb and resource ('The Tillhub user behind the API key') and enumerates the fields returned (role, scopes, account id and name). It implicitly distinguishes itself from the entity-lookup siblings by clarifying this is the caller's own identity rather than a lookup by id, though it never explicitly contrasts itself with a sibling.

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

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

Usage is only implied: an agent can infer this is the right call for 'who am I / what am I allowed to do', but the description never states when to use it, when not to, or how it relates to the many list/get siblings. No explicit alternatives or prerequisites are given.

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 only the raw endpoint path and says nothing about not-found behavior, auth requirements, or what the response contains.

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 the scoping information front-loaded and no filler. It is terse to the point of being telegraphic, but nothing is wasted.

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

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

For a single-parameter read tool whose annotations carry the safety profile and whose schema fully documents the id, this is close to sufficient. It still leaves the agent guessing about lookup failure behavior and the shape of the returned customer.

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

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

Only one parameter and schema coverage is 100%, with the schema documenting it as a Tillhub customer uuid and giving a pattern and length bounds. The description adds no meaning beyond 'by id', 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+resource ('One customer by id') plus the backing endpoint, so the agent knows this is a single-record fetch. Sibling differentiation is only implicit via 'one' versus the list/search variants; no sibling is named.

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

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

No guidance on when to use this versus tillhub_list_customers, tillhub_search_customers, or any other sibling. The agent must infer that 'by id' means it already has an identifier.

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 that the branch parameter pulls branch-specific stock and prices plus the underlying endpoint path, but says nothing about behavior when the id is unknown or the branch is invalid.

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: the functional statement comes first, the endpoint reference last. Nothing is redundant or 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?

For a two-parameter read-only lookup with no output schema, the definition tells the agent what is retrieved and what the optional parameter adds. Only the shape of the returned product and error behavior are left unstated, which is acceptable given the 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 100%, so both parameters are already documented; the description only adds that branch is optional and that it yields stock and prices rather than stock alone, a marginal gain over the schema's 'branch-specific stock 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 verb+resource and scope: a single product fetched by id, optionally enriched with stock and prices for one branch. The 'by id / one product' phrasing implicitly separates it from the list_products and search_products siblings, though it never names them.

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

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

The 'by id' scope implies when to use it over list_products or search_products, but there is no explicit guidance, no prerequisites, and no statement about when the branch argument should be supplied.

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 profile is covered. The description adds useful shape information (the response includes cart, payments and taxes) and the underlying endpoint, but says nothing about not-found handling or result size for a possibly heavy nested 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 short sentences, front-loaded with what is returned, followed by the endpoint path. No filler, though the raw endpoint string is of marginal value to an agent compared to more behavioral detail.

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 burden of describing returns and does so at a high level (cart, payments, taxes). For a one-parameter read tool this is nearly complete; only error/empty-result behavior is unaddressed.

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

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

Schema description coverage is 100% and the single parameter is fully documented (uuid, pattern, 1-100 chars). The description only restates "by id" and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

"One transaction by id with its full cart, payments and taxes" names a specific verb (retrieve), resource (transaction), and scope (single, by id), which implicitly separates it from tillhub_list_transactions. It stops short of explicitly naming that sibling, so an agent must infer the single-vs-list split.

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

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

Usage is only implied: the phrase "by id" signals this is for fetching a known transaction, versus listing or reporting. There is no explicit when-to-use, no exclusion of the list/report siblings, and no statement about what happens if the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine behavioral detail beyond them: the result content (totals per register and day), the pagination mechanism ('Page with next_query'), and the underlying endpoint — useful since there is no output schema.

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

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

Three short clauses: what it returns, how to filter, how to page, plus the route. Front-loaded and free of filler; every sentence earns its place.

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

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

With no output schema and six optional params, the description covers the returned data shape, filtering and paging well. It is slightly thin on the temporal dimension — the report is 'per day' yet nothing says how days/periods are selected or defaulted — but otherwise enough to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description names the branch/register/staff filters and next_query but adds no semantics the schema lacks (the schema already explains next_query carries the filters and that the other arguments are then ignored), and the free-text 'query' parameter is never mentioned.

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 cash-register closings') and adds the synonyms balances / Z-reports plus what the payload contains ('totals per register and day'). That distinguishes it clearly from siblings like tillhub_list_registers (registers themselves) or tillhub_transactions_report.

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

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

'Filter by branch, register or staff' gives context for narrowing results, but there is no statement of when to pick this over tillhub_revenue_sum, tillhub_sales_aggregate or tillhub_transactions_report, and no prerequisites or exclusions. Usage is implied rather than instructed.

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 the returned field set and the GET endpoint, but says nothing about result volume, ordering, or what an empty result means; the next_query argument-ignoring rule is already in the schema, so it earns no extra credit here.

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 purpose, then usage, then pagination. Every clause carries information and nothing is repeated from the schema verbatim.

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 five-parameter read-only list tool with full schema coverage and no output schema, the description covers purpose, record contents, pagination and downstream use of ids. A brief note on what the response envelope looks like or on default ordering would close the remaining gap.

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

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

Schema description coverage is 100%, so name, query, active, limit and next_query are fully documented in the schema. The description adds no filtering guidance (e.g., name vs. query, which to use for exact vs. fuzzy matching), so it only meets the baseline for a fully-described schema.

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

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

Specific verb+resource ("List branches") with the useful clarification that branches are shops and a statement of what each record contains (number, name, address). It does not name a sibling tool explicitly, but the pointer to using returned ids for transactions/stock/prices implicitly separates it from the list_* siblings.

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

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

"Use the ids to filter transactions, stock and prices" gives a concrete reason to call this before the transaction/stock/price tools, and "Page with next_query" tells the agent how to continue. There is no explicit when-not or named alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the pagination mechanic (next_query) and the underlying endpoint, but does not say whether results are capped, ordered, or how many pages are typical — modest added context beyond 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, front-loaded sentences with no filler; the returned fields come first, then filters, then pagination. The trailing 'GET /api/v1/customers/{account}' is of marginal use to an agent and is the only sentence that does not clearly earn its place.

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

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

With 10 optional parameters, no output schema and no annotations gap, the description is adequate but thin: it never explains what a result item looks like beyond a field list, how next_query should be threaded, or why one would pick this over the search_customers sibling. Enough to call it, not enough to call it optimally.

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

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

Schema description coverage is 100%, so every one of the 10 parameters is already documented in the schema. The description's filter enumeration largely restates those fields without adding syntax or precedence rules beyond what the schema says (e.g. that customer_number ignores other filters). 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 ('List customers') plus the fields returned (name, company, email, phone, addresses) and the filter dimensions. However, it never distinguishes itself from the sibling tillhub_search_customers, which an agent must choose between, so it falls short of a 5.

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

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

Usage is only implied: the filter list suggests 'use this to browse/filter customers,' and 'Page with next_query' implies repeated calls. There is no explicit when-to-use guidance and no statement of when to prefer tillhub_search_customers or tillhub_get_customer instead.

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 state readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the REST endpoint path, which hints at account scoping but does not explain pagination, filtering behavior, or result size; the extra sentence barely adds value beyond structured data.

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 very short and front-loads the purpose. The endpoint path is somewhat redundant but not harmful, and there is no filler prose.

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, read-only list tool with full schema coverage and annotations, the description is minimally adequate. However, it does not mention account scoping requirements, pagination behavior, or what fields a discount record contains, leaving notable gaps for an agent invoking 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 100%, with each of the three optional parameters clearly documented in the schema itself. The description adds no parameter detail, so the baseline score of 3 applies when the schema does all the work.

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 clear verb and resource ('List configured discounts'), so an agent knows exactly what is returned. It does not, however, differentiate this from sibling list tools such as tillhub_list_products or tillhub_list_taxes beyond the resource name.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of pagination strategy despite the next_query parameter. The agent is left to infer everything from the name.

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 only the pagination note and the endpoint path; it says nothing about result size, ordering, or error conditions beyond what the schema already documents.

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

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

Two short sentences with the key scope and paging hint front-loaded. The trailing raw endpoint is mildly redundant but not harmful.

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

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

For a read-only list tool with a fully documented 4-parameter schema and no output schema, the definition covers scope and pagination adequately. It could say more about what an order record contains, but nothing essential for invoking 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 description coverage is 100%, so limit, deleted, direction and next_query are fully documented in the schema. The description reinforces paging via next_query but adds no semantics beyond that, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource and clarifies what an 'order' means here (goods orders between locations/suppliers), which disambiguates it from the transaction/product siblings. It does not explicitly name an alternative tool, but the resource is distinct enough that confusion is unlikely.

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 mention of 'Page with next_query' implies the typical retrieval workflow, but there is no explicit when-to-use guidance, no prerequisites, and no comparison to sibling list tools such as tillhub_list_transactions or tillhub_list_stock.

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 fully covered elsewhere. The description adds only the account scoping and the REST endpoint, not return shape, pagination semantics (despite the next_query param), or auth requirements.

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

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

Two short sentences with the core purpose front-loaded. The raw endpoint path at the end is marginal filler but does not obscure the purpose.

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 two-parameter, read-only listing tool with full schema coverage and clear annotations, the definition supplies enough for an agent to call correctly. Missing pagination behavior detail is a minor gap since next_query is documented 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 description coverage is 100%, including a clear explanation of the pagination token and the active filter, so the schema carries the parameter burden. The description adds nothing about the active or next_query arguments, which is acceptable at this coverage level but not additive.

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 payment options') and clarifies with examples of what a payment option is (cash, card, voucher). No sibling tool covers payment options, so differentiation is implicitly handled by the unique resource.

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

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

Use is implied by 'list ... configured for the account', but there is no explicit statement of when to use this versus other listing tools or any prerequisite context. Given no sibling overlaps on this resource, the inference cost is low, so a 3 rather than lower.

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 the underlying endpoint (GET /api/v0/product_groups/{account}) and the returned shape, but says nothing about pagination behavior, result limits, or whether all groups are returned by default—gaps that matter for a list tool.

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

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

Two short sentences with zero filler; the purpose is front-loaded and the endpoint reference trails it. Nothing is wasted 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?

For a read-only list tool with full schema coverage and no output schema, the definition is nearly complete: purpose, resource, returned fields, and endpoint are all present. Only pagination semantics and default-scope behavior are left implicit, relying on the schema's next_query description.

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 each of the three optional parameters (active, deleted, next_query) is already documented in the schema, including the important note that next_query overrides other arguments. The description adds no parameter meaning beyond that, 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 ('List product groups') and adds a clarifying synonym '(categories)' plus the returned fields (id and name). An agent can distinguish it from tillhub_list_products or tillhub_list_tags by resource name alone, though no explicit sibling contrast is given.

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 offers no when-to-use guidance, no mention of the available filters (active/deleted), and no comparison to alternative listing or search tools. The agent must infer usage from the name and schema 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/non-destructive/openWorld, so the bar is lower; the description adds real behavior beyond that by disclosing that barcode/custom_id and next_query short-circuit the other arguments and by naming the backing endpoint. It omits return shape details and pagination limits, which 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 front-load the resource and returned fields, then filters, then the pagination mechanism, with no filler. Every clause carries information an agent can act on.

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

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

With 11 optional parameters and no output schema, the description compensates well by enumerating returned fields and explaining paging via next_query. It leaves the limit default and enum type values to the schema, which is acceptable given full schema coverage.

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 most parameter meaning is already carried by structured fields, and much of the description's filter talk (barcode/custom_id ignoring filters, next_query containing filters) restates it. It adds only the 'fast exact lookup' nuance, so baseline 3 fits.

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?

Opens with a specific verb (List) and resource (products), and enumerates the subtypes covered (articles, variants, vouchers) plus the fields returned, so an agent knows exactly what it gets back. It does not differentiate itself from the sibling tillhub_search_products or tillhub_get_product, which keeps it from 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?

Gives concrete conditions for filter use, including that barcode and custom_id are fast exact lookups that override other filters, and that next_query drives paging. It provides context but no exclusions telling the agent when to prefer search_products or get_product instead.

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 the underlying endpoint and that receipts may be printed or digital, but says nothing about ordering, whether all account receipts are returned, or what the response shape 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 terse fragments with the resource stated first and no padding. The endpoint reference is useful for developers but is the least essential piece given the surrounding context.

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

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

For a two-parameter list tool with no output schema and full schema coverage, the essentials are present, but the description never states what happens on a first call without next_query, what ordering is used, or what a receipt record contains — details an agent needs to interpret results.

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

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

Schema coverage is 100%: limit bounds and the next_query precedence rule ('other arguments are ignored') are fully documented in the schema. The description's 'Page with next_query' merely echoes that, adding no new semantics, 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 ('List receipts') and clarifies the scope as receipts of the account, with the printed/digital distinction adding a bit of domain meaning. It does not differentiate from the closest sibling, tillhub_list_transactions, leaving the agent to infer the receipts-vs-transactions boundary.

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 signal is 'Page with next_query', which explains pagination mechanics rather than when to choose this tool. There is no guidance on when to use it instead of tillhub_list_transactions or tillhub_get_transaction, and no prerequisites or exclusions.

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 adds the underlying endpoint and the shape of what comes back, but says nothing about result size, pagination behavior, required permissions, or how account scoping works.

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

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

Two sentences, zero waste, with the core purpose front-loaded and the endpoint detail trailing it. Nothing could be cut without losing information.

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

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

For a read-only filtered list with full schema coverage and no output schema, the description gives the returned fields and the endpoint, which is close to sufficient. A note on pagination expectations or the default result set would make it complete.

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

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

Schema description coverage is 100% and all four parameters carry descriptive text, including next_query's note that it overrides the other filters. The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List cash registers') and even enumerates the returned fields (number, name, branch), which distinguishes it from near-miss siblings like tillhub_list_branches. It stops short of explicitly routing against any sibling, so it is clear but not differentiating by contrast.

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 explicit when-to-use or when-not-to-use statement, nor any pointer to an alternative tool. Usage is only implied by the name and by the filter parameters, which is the definition of minimum-viable 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 carry readOnlyHint/openWorldHint/destructiveHint, so the bar is lower, and the description still adds real value: it guarantees PINs and passwords are never returned, a security-relevant behavioral fact not derivable from structured fields. It also discloses the underlying endpoint. It stops short of describing result volume or pagination behavior, which keeps it from a 5.

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

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

Three short sentences, everything front-loaded: scope first, safety guarantee second, endpoint last. No sentence is redundant and nothing is 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?

A read-only list tool with fully documented optional parameters, an explicit statement of returned fields, and a guarantee about suppressed sensitive data — the main things an agent needs. Pagination semantics live entirely in the next_query schema entry rather than the description, a minor gap but not a functional one.

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 all four parameters (query, active, branch, next_query) are documented in the schema, so the baseline is 3. The description does not add filter semantics or clarify how 'branch' interacts with the returned 'branch' field, leaving the schema to do all the work.

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 (list) plus resource (staff members/cashiers), and it names the fields returned (name, number, branch), which no sibling list_* tool does. The resource is distinct from siblings like tillhub_list_branches or tillhub_list_registers, so an agent can disambiguate without opening the schema. No explicit sibling routing, so not 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?

Usage is implied by the resource name — an agent asking 'who works here' will select it — but there is no statement of when to prefer it over alternatives, no prerequisites, and no mention that pagination continues via next_query. It is adequate rather than instructive.

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 adds that results are 'current' and exposes the REST path, but says nothing about pagination behavior beyond what the next_query schema field implies, nor about rate limits or result size.

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, front-loaded sentences with no filler. The purpose is stated first, followed by filtering guidance and the endpoint, so an agent can parse it quickly.

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

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

For a read-only list tool with full schema coverage and annotations covering safety, the description is nearly sufficient. It could be stronger by clarifying how it differs from stock_book/stock_locations and by hinting at the returned stock fields, but nothing critical for invocation 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 description coverage is 100%, so all three parameters are already documented (including next_query's pagination and filter-override behavior). The description's 'branch/warehouse id' clarification largely duplicates the schema's 'Location id (branch or warehouse)' and does not mention next_query at all, so it adds little beyond 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 verb ('List') and resource ('stock levels'), plus scope ('Current stock per product and location'). However, it does not differentiate from close siblings like tillhub_list_stock_book or tillhub_list_stock_locations, so an agent still has to infer which stock-related tool to pick.

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 explains how to filter ('by location ... or product id') but gives no guidance on when to use this tool versus alternatives such as tillhub_list_stock_book. No exclusions, prerequisites, or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the REST endpoint (GET /api/v1/stock/{account}/book), with no disclosure of result volume, defaults, or pagination limits beyond what the schema already says.

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: what it is, how to narrow, how to page. No filler, and the defining content (movement ledger with fields) comes first.

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 7 optional params, no output schema, and no required arguments, the description does enough: it sketches the returned record fields and points at next_query for paging. A note on result ordering or default page size would close the remaining gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail (ISO formats, 1-100 limit, next_query semantics). The description's mention of product/location/period/text filters and next_query only mirrors the schema without adding syntax or edge-case meaning.

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

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

Names the resource precisely ("Stock book: every stock movement") and enumerates the movement kinds (sale, delivery, correction, transfer) plus the fields carried (product, location, quantity, date). This distinguishes it clearly from tillhub_list_stock, which is about current levels rather than the movement ledger.

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

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

The description gives filtering and paging hints but never states when to prefer this over tillhub_list_stock or tillhub_list_stock_locations, nor any exclusions. Usage is implied by the movement-ledger framing rather than spelled out.

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/destructiveHint=false, so safety is covered. The description adds the endpoint path (confirming a GET), consistent with the annotations, but says nothing about result pagination or result size — a relevant behavioral trait given next_query.

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

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

Two short clauses, front-loaded with purpose. The trailing raw endpoint path is marginal filler for an agent but costs little.

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 read tool with full annotations and a fully documented parameter, most is covered. However, with no output schema, the description's return-value disclosure ("with their ids") is minimal and pagination behavior is left unstated.

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

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

Single parameter with 100% schema description coverage; the schema fully explains next_query's role and that other args are ignored on continuation. The description adds nothing beyond that, which is the baseline expectation.

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

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

States a specific verb (List) and resource (stock locations), and the parenthetical "(branches and warehouses)" clarifies scope in a way that separates it from the plain tillhub_list_branches sibling. It stops short of explicitly contrasting itself with that sibling, so not a 5.

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

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

No guidance on when to use this versus tillhub_list_branches or tillhub_list_stock, and no mention of pagination workflow despite a next_query parameter existing. Usage is only weakly implied by the verb.

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, non-destructive, open-world behavior, so the bar is low, yet the description adds nothing beyond the endpoint path. It does not mention pagination behavior, result caps, or that a tag list may be account-scoped — details that would help an agent plan calls.

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, front-loaded sentences with zero filler; the resource comes first. However, the endpoint path is arguably filler for an agent that does not need HTTP routing details.

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

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

For a simple, annotation-backed list tool with fully described parameters and no output schema, the essentials are present. Still, an agent gets no sense of result shape (fields on a tag) or pagination cadence, which the description could have covered in one clause.

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

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

Schema coverage is 100% and each of the three parameters (query, deleted, next_query) is documented in the schema itself. The description adds no extra meaning about filtering semantics or how query interacts with deleted, 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 ('List product tags') plus the underlying endpoint, which is unambiguous. Siblings are all distinct resources, so no explicit differentiation is needed, but the description stops short of saying what a tag contains or how results are ordered.

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

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

Usage is only implied — an agent infers this is a read-only enumeration of the tag catalog. There is no statement about when to call it (e.g. before assigning tags to a product) or how it relates to the filter parameters.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds little beyond confirming a GET endpoint and noting rates; it does not mention pagination, authentication, or output behavior, so it is minimally sufficient but not rich.

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

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

The description is two short, front-loaded sentences with no wasted text. The purpose and endpoint are stated immediately.

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 read-only list tool with complete parameter descriptions and explicit annotations, the description gives enough context to call it correctly. It could mention pagination behavior more directly, but the schema already covers next_query.

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 both the active and next_query parameters are already fully documented. The description adds no parameter-level details, which is acceptable at this coverage level but does not exceed baseline.

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

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

The description names a specific verb and resource: list tax/VAT references with rates. It is distinguishable from siblings because no other sibling deals with taxes, though it does not explicitly state why it differs from other list tools.

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

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

It does not say when to use this tool versus alternatives or when not to use it. It also omits guidance on filtering by active status or using next_query for pagination, leaving that entirely to the schema.

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 two real behavioral traits: the performance pitfall of unbounded date ranges on busy shops and the fact that paging is done via next_query from the prior reply. It does not discuss rate limits or result volume, but the annotations already cover the safety profile.

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

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

Four short sentences, front-loaded with the resource and filter surface, then the date-range warning and pagination note, then the endpoint. Nothing is redundant or 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?

With 10 optional params and no output schema, the description usefully previews the returned shape (amounts, payments, cart items) and covers pagination, which is what an agent needs to call it correctly. It stops short of explaining how to follow the next_query chain or what to do when no date range is known.

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

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

Schema description coverage is 100%, so every parameter already carries meaning in the schema; the description's parenthetical list of filter dimensions largely restates them. No extra syntax or constraint detail is added, so the baseline 3 applies.

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

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

States a specific verb and resource ('List sales and other register transactions') and enumerates the filterable dimensions (type, date, branch, register, staff, customer). It implicitly contrasts with the single-record sibling tillhub_get_transaction by being a list, but never names any sibling such as tillhub_transactions_report or tillhub_list_orders.

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

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

'Always pass a date range for busy shops' is a concrete usage rule and 'Page with next_query' implies the iteration pattern, but there is no explicit when-to-use-this-vs-alternatives guidance despite many overlapping siblings (reports, aggregates, receipts, orders).

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 only the underlying REST path, and says nothing about aggregation semantics that matter for a revenue total (currency handling, whether refunds/taxes are included) or about paging limits, so it adds modest value beyond 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?

One front-loaded sentence plus the endpoint path; there is no filler. The raw path adds little for an agent but is short and does hint at the account scoping not present in the schema.

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

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

For a read-only aggregation over 4 fully-documented params with no output schema, the definition is workable but thin: it does not indicate what the sum returns (a scalar vs. a per-branch/per-currency breakdown) or how paging via next_query interacts with the totals, which are the facts an agent would most want before trusting the number.

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 start/end formats, the branch_number 'not the id' caveat, and next_query's 'other arguments are ignored' behaviour are already documented in the schema. The description only re-states that branch_number is optional, which is marginal added meaning.

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

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

States a specific computed resource (total revenue) with its scope (between two points in time, optionally one branch), which is clearly distinct from the list/get siblings. It does not explicitly differentiate itself from the closer analytics siblings such as tillhub_sales_aggregate or tillhub_transactions_report, so an agent must infer which aggregate to pick.

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

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

The description never says when to use this versus tillhub_sales_aggregate, tillhub_top_products, or tillhub_transactions_report, nor does it state prerequisites or exclusions. Usage is only implied by the phrase 'total revenue between two points in time'.

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 nothing behavioral beyond that: it does not mention pagination behavior, result caps, or that filters are carried inside next_query. It essentially restates what the annotations and schema already provide.

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 operation and its cadence; nothing is padded. The trailing endpoint reference is mildly redundant but useful for API-oriented agents.

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

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

There is no output schema, so the description should at least sketch what the aggregate response contains or how paging works. It never mentions the pagination contract implied by next_query or the branch scoping, leaving meaningful gaps for a reporting 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 100%, so start, end, precision, next_query, and branch_number are all documented in the schema itself. The description adds no additional semantic detail (e.g. default precision behavior, whether next_query invalidates other args), so it earns the baseline 3 rather than more.

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+scope: sales and revenue aggregated per hour or per day over a time window. The API endpoint is included. However, with siblings like tillhub_revenue_sum and tillhub_transactions_report present, the description never explains how this aggregation differs from those, so differentiation is left to the agent.

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 tillhub_revenue_sum, tillhub_transactions_report, or tillhub_top_products, which all touch revenue. The description also omits any prerequisite or pagination flow context (e.g. that next_query yields the following page).

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 the safety profile is covered. The description adds real behavioral detail on top: fuzzy/partial matching semantics, a hard 100-hit ceiling, and that results carry a relevance score. It does not describe paging behavior or what ordering to expect.

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

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

One front-loaded sentence that carries the verb, scope, searched fields, result cap and ranking in a compact form. The trailing 'GET /api/v2/customers/{account}/search' is redundant API trivia that adds nothing for an agent already holding the tool.

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-shape burden and does so adequately by noting a relevance score and a 100-hit maximum. For a three-parameter read-only search that is enough to call correctly, though pagination expectations remain unstated.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by naming the fields actually searched (name, email, description), which the schema's generic 'Search text' does not reveal. The 100-hit cap also corroborates the limit parameter's maximum, though offset/paging is left entirely to 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 ('Fuzzy search customers') plus the searched fields (name, email, description), which plainly separates it from the sibling tillhub_list_customers. It stops short of explicitly naming that sibling or stating that it enumerates rather than text-matches.

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 word 'fuzzy' signals to reach for this when text is partial, and the 100-hit cap hints at exploratory queries. The description never says when to prefer tillhub_list_customers or tillhub_get_customer, nor does it state prerequisites or exclusions.

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 safety is covered and the description only needs to add behavioral detail. It does add the 20-hit page cap and that results carry a relevance score, but it never explains how fuzzy matching behaves (typos, partial words, ranking) or whether results are account-scoped.

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

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

One compact sentence plus a bare endpoint path; the core capability and the page-size constraint are front-loaded with no padding. The trailing URL is of marginal value to an agent compared with what could have occupied that space, keeping it out of 5 territory.

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 carries the burden of describing what comes back, and it only mentions hits and a relevance score without saying what a hit contains. For a low-complexity search with fully documented params this is adequate but leaves the return shape underspecified.

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

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

Schema description coverage is 100%, with limit, query, offset and sellable all documented in the schema including bounds. The description adds only that matching is against name and description, which is a small increment over the schema baseline.

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 ('fuzzy search products by name and description') plus the underlying endpoint, which is enough to tell it apart from a plain listing tool. It never names the sibling it differs from (tillhub_list_products), so it stops short of full differentiation.

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 word 'fuzzy' implies an exploratory text-search use case versus enumerating products, so the intended situation is inferrable. But there is no explicit 'use this when you have partial text, use tillhub_list_products when browsing' guidance or any exclusions.

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 only the underlying endpoint path, with no note on result set size, pagination behaviour, or what a missing branch_number falls back to.

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 metric and scope, with no filler. The raw endpoint line is of marginal use to an agent but does aid traceability.

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 would need to hint at the return shape, but it never says what a 'top product' entry contains or whether the list is ranked or truncated. For a reporting tool with zero output schema, that leaves a real gap.

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

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

Schema description coverage is 100%, so all four parameters are fully documented in the schema itself. The description only gestures at 'period' and 'branch number', adding no format or boundary detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource and metric: best-selling products over a period, optionally scoped to a branch. That clearly separates it from list_products or search_products, which do not rank by sales, though it never names those siblings explicitly.

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

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

The analytics framing and 'period' scoping imply a reporting use case, but there is no explicit when-to-use, no prerequisites (account id, auth), and no discrimination against related reporting siblings like tillhub_sales_aggregate or tillhub_revenue_sum.

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 the period-scoping trait and the underlying endpoint, but omits pagination behavior for a large result set (the next_query loop is only explained in the schema), which matters for a reporting tool.

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

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

Two sentences, front-loaded with the purpose before the endpoint reference, with no filler. The raw endpoint path is somewhat redundant for an agent-facing definition but is short and harmless.

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 9-parameter, no-output-schema reporting tool, the description covers what it filters on but says nothing about the result shape, granularity, or volume, and silent on the pagination pattern an agent must implement. Adequate but with clear gaps that matter for a 'detailed report' 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 100%, so every parameter (including the ISO 8601 date formats and next_query semantics) is already documented in the schema; baseline 3 applies. The description's filter list (branch, register, staff, customer, type, currency) merely restates schema fields and adds no format or usage detail.

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

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

States a specific verb+resource ('Detailed transactions report') scoped to a period with an explicit filter list, which is more specific than a bare name restatement. However, it never names or contrasts with the closest siblings (tillhub_list_transactions, tillhub_revenue_sum, tillhub_sales_aggregate), so an agent must infer how this 'report' differs from simply listing transactions.

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?

'For a period' hints that date_start/date_end scope the call, but there is no explicit when-to-use guidance and no mention of when to prefer list_transactions, revenue_sum, or sales_aggregate. The agent is left to guess the choice among four transaction-related siblings.

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