Agua e Vida — On-Demand Purified Water Delivery & Refills

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

The description adds meaningful behavior beyond annotations: zero state mutation, public unauthenticated access, and a rate limit of 60 requests/min per IP. These are operationally relevant details for invoking the tool correctly and do not contradict the read-only, idempotent annotations.

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

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

The definition is front-loaded with the core purpose and organized into useful usage, behavior, and return sections. It loses some efficiency because the when-to-use sentence is tautological and the parameter line duplicates 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 one-parameter read-only lookup with full annotation coverage, the description supplies the remaining context an agent needs: scope, alternatives, auth/rate-limit behavior, and a return-shape summary despite there being no output 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?

The single parameter has 100% schema description coverage with examples, so the schema already carries the semantic burden. The description only repeats that address_or_suburb is required and adds no format or interpretation guidance beyond the schema.

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

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

The first sentence states a specific verb and resource: checking delivery eligibility for an address or suburb and calculating estimated fees, scoped to Pretoria/Gauteng purified water delivery. This is clear enough for an agent to distinguish it from product, cart, and order-status 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?

It explicitly names alternatives such as list_products, create_checkout_cart, and track_order_status and says not to use this tool when another specialized tool fits. However, the positive when-to-use guidance is circular ('when you specifically need to execute check_delivery_coverage') rather than stating a concrete selection condition.

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

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

Against annotations that already declare openWorldHint=true, destructiveHint=false and idempotentHint=false, the description adds genuinely useful context: a live backend record is created, no authentication is required, and there is a 60 req/min per-IP rate limit. It misses the practical consequence of idempotentHint=false — that repeated calls create duplicate carts — which would be the most valuable warning 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?

The first sentence is front-loaded and useful, but the 'When to use' sentence is tautological filler and the trailing 'Returns' sentence is generic boilerplate ('matched records or computed metrics') that does not match a checkout-creation tool and may mislead. Roughly half the text does not 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?

For a 6-parameter mutation with annotations present and no output schema, the essentials are mostly covered. Gaps remain: no warning that the tool is non-idempotent, no statement of what the returned checkout link looks like or how long it lives, and the 'Returns' line is generic rather than tool-specific.

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 every parameter, including the nested item shape, is already documented in the schema. The description's parameter list only repeats names and required/optional status without adding format, constraint, or interaction details, 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?

The opening sentence states a specific verb and resource — 'Create a pre-filled 1-click checkout link' — plus the scope (customer, selected items, delivery info). It is immediately distinguishable from the read-only siblings (list_products, check_delivery_coverage, track_order_status) named later in the text.

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 name three alternative tools to use instead, which gives some routing signal. However the positive condition is pure boilerplate — 'Call this tool when you specifically need to execute create_checkout_cart' restates the name rather than describing the situation, and it never says when a checkout cart is appropriate (e.g. after the customer confirms items).

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 safety is covered; the description still adds genuinely new context: public unauthenticated access and a 60 requests/min per-IP rate limit. It also sketches the return shape (status, matched records/metrics, canonical action URLs), which the annotations do not.

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 rate-limit and return-shape sentences earn their place, but the 'When to use: Call this tool when you specifically need to execute get_dispenser_rental_info' sentence is circular filler that could be deleted. The useful signal is buried in a boilerplate template.

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

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

There is no output schema, but the description outlines the return structure, and with annotations covering safety plus the added auth/rate-limit details, an agent has enough to call it correctly. Minor gaps remain around the actual rental plan attributes returned.

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?

This is a zero-argument tool; the description confirms it as a 'zero-argument query' with no required parameters. That matches the schema, so the baseline 4 applies without further param detail needed.

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 opening sentence clearly names the resource (dispenser rentals for hot & cold water coolers, including 40L monthly refill credits and rental pricing), which distinguishes it from the sibling tools. The follow-up 'when to use' sentence, however, is circular boilerplate that just restates the tool name.

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

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

It names the alternative siblings (list_products, check_delivery_coverage, create_checkout_cart) and tells the agent not to use this tool when those fit better. But the positive guidance is tautological ('when you specifically need to execute get_dispenser_rental_info'), so the agent still has to infer when rental-pricing queries genuinely apply versus browsing products.

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 bar is low, yet the description still adds genuinely new facts: unauthenticated public access and a 60 requests/min per IP rate limit, both of which affect agent retry behavior. The returns sentence is templated boilerplate ('matched records or computed metrics') that does not describe a store-info payload, which dilutes the value slightly.

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 payload list is well front-loaded, but the middle of the description is wasted on a self-referential 'when to use' sentence and a generic returns clause that reads as boilerplate. Roughly a third of the text does not 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 no output schema, the description must carry the return-value burden, and what it offers ('status, matched records or computed metrics, and canonical action URLs') is generic template text rather than a description of the actual store info object. A zero-argument read tool does not need much more, but the return shape remains unpinned.

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?

Zero parameters, so the baseline is a 4; the description correctly confirms this with 'none required (zero-argument query)', removing any doubt about whether arguments are expected. There is nothing further to specify.

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 opening sentence names a specific resource and enumerates the concrete payload: store location, trading hours, contact numbers, WhatsApp link, and purification technology overview. It is clearly distinguishable from the transactional siblings, though the second sentence's 'when to use' clause merely restates the tool name rather than sharpening the purpose.

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

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

It explicitly gives a do-not-use clause and names three concrete alternatives (list_products, check_delivery_coverage, create_checkout_cart), which is real routing guidance. The positive 'when to use' clause is circular — 'when you specifically need to execute get_store_info' — so the selection condition for using this tool is never actually stated, only the 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, idempotentHint, openWorldHint and destructiveHint, so restating read-only/idempotent adds nothing. The description does earn credit by disclosing things annotations cannot: public unauthenticated access, a 60 requests/min per-IP rate limit, and the general shape of the returned JSON.

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?

Content is front-loaded, but the 'When to use' sentence is pure tautology that restates the tool name and burns space without informing the agent. The templated 'Returns: Structured JSON object containing status, matched records or computed metrics' is also generic filler rather than catalog-specific output guidance.

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

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

For a one-optional-param read tool with full schema coverage and complete annotations, the description covers auth model, rate limits, and return shape, which is sufficient to invoke it correctly. Only the boilerplate usage sentence and generic return wording keep it from being fully complete.

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

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

Schema description coverage is 100% and the single optional 'category' param already carries examples in the schema. The description's 'Parameters: category (optional)' merely repeats that, adding no filtering semantics beyond what the schema provides, 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?

The opening sentence gives a specific verb (fetch) and resource (live Agua é Vida product catalog) and enumerates the concrete contents: 20L refills, BPA-free bottles, dispensers, accessories, and ZAR pricing. An agent immediately knows this is a catalog read, not an order or coverage query.

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 'Do NOT use this tool when...' clause names three siblings (check_delivery_coverage, create_checkout_cart, track_order_status), which is useful routing. However, the 'When to use' clause is circular boilerplate ('Call this tool when you specifically need to execute list_products') and the exclusions say only 'for their respective operations' without stating the condition that selects each alternative.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the description repeats some of that ('strictly read-only, idempotent, zero state mutation'). It does add genuinely new context the annotations cannot express: rate limiting of 60 requests/min per IP and unauthenticated public access, which matter for retry strategy.

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?

Purpose and alternatives are front-loaded, but the 'When to use' clause is tautological filler, and the 'Behavior & Side Effects' / 'Returns' scaffolding is heavier than the content warrants. It is readable but not tight.

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 shape (status, matched records, action URLs), and annotations plus the rate-limit note cover safety and operational constraints. The gap is minor: no mention of what happens when neither identifier is supplied, despite both being optional.

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 schema already explains both optional parameters with example formats (AG-TEWFY9, 0765112555). The description only restates that they are optional and adds no semantics such as which key takes precedence when both are supplied or what happens with neither.

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 first sentence gives a specific verb (track), a specific resource (order status, litre balance, delivery progress) and the lookup keys (order number or phone). It clearly separates this from the sibling tools, which handle product listing, coverage checks, and cart creation.

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

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

The 'When to use' sentence is circular — it tells the agent to call track_order_status when it needs to execute track_order_status, which adds nothing. The exclusion clause does name three relevant siblings (list_products, check_delivery_coverage, create_checkout_cart), but merely says 'for their respective operations' without stating the conditions that select each, so the agent must infer the boundaries.

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