smile-io

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

Adds substantial behavior beyond the thin annotations (destructiveHint only): asynchronous earning-rule evaluation that may issue points or rewards, idempotency semantics with the specific rejection case for duplicate token+distinct_id, plan gating, and required scope. This tells the agent the side effects and failure mode of a write it cannot see from the schema.

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

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

Front-loaded with 'WRITE:' and the core action, then packed with operational constraints in a few dense sentences; little is wasted. It is information-heavy rather than elegantly trimmed, but every sentence carries weight.

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

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

With no output schema, no return-value description is strictly required, and the description covers async processing, idempotency, scope, and plan requirements for a 5-parameter write tool. Only a note on what the call returns or how the async outcome is observed is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: token is a token configured in Smile Admin, distinct_id is exemplified as an order number, and the customer_id/customer_email mutual-exclusivity rule is stated. It extends rather than repeats 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?

Opens with an explicit verb+resource ('WRITE: record that a customer performed an action') and pins the resource to a configured activity type token, finishing with the underlying call (Smile: POST /activities). This is clearly distinguishable from the points-transaction and rewards siblings, which record different resources.

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

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

Gives concrete conditions: exactly one of customer_id or customer_email, use distinct_id to make the call idempotent, custom activity types require Plus/Enterprise, and the activity:write scope is needed. It stops short of naming a sibling alternative (e.g. when to reach for smile_create_points_transaction instead), so it is strong but not exhaustively routing.

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

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

Annotations only supply destructiveHint=true; the description carries the rest of the burden. It discloses the negative-balance rejection rule, the reversibility strategy, customer-visible vs merchant-only field exposure, the required points_transaction:write scope, and the underlying endpoint. That is rich behavioral context beyond the single annotation.

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?

Five compact sentences, each carrying distinct information: modality, sign semantics, safety rule, undo path, field visibility, alternative tool, auth scope, endpoint. The most decision-critical facts (WRITE, add/deduct) are front-loaded with no filler.

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

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

With no output schema and only a destructiveHint annotation, the description supplies everything needed: write semantics, failure mode, reversal, permission requirement, and the alternative tool. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the description still adds meaning: it explains the sign convention as a business rule (positive adds, negative deducts, rejection when it would go negative) and clarifies the customer-visible vs merchant-only split between description and internal_note. It distinguishes which fields have side effects for the customer, going beyond the schema labels.

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

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

The description opens with a specific verb+resource+modality ("WRITE: add or deduct points from a customer's balance") and immediately qualifies it as a manual adjustment with examples (goodwill credit, correction). It explicitly contrasts with the sibling smile_create_activity for action-based rewards, so an agent can route without opening sibling schemas.

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

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

It states the when-to-use case (manual adjustments, not action rewards), names the preferred alternative for rewarding completed actions, and documents the undo path (create an opposite adjustment). Conditions and alternatives are explicit rather than inferred.

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

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

readOnlyHint=true already declares this as a safe read. The description goes further by disclosing the underlying endpoint (GET /customers/{id}) and, importantly, the exact fields returned — significant since no output schema exists. It stops short of describing error behavior for an invalid ID or any response envelope details.

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, no filler: the identity/scope and field list lead, the optional include behavior follows, and the endpoint reference is appended. Every clause 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, the description compensates well by listing the returned fields and the optional VIP expansion. Minor gaps remain around failure modes and whether the include parameter is required for VIP data, but nothing essential for a correct 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 coverage is 100%, so the baseline would be 3. The description adds real meaning by explaining that the optional payload is VIP status with current and next tier, which maps the include enum values to a concrete outcome for the caller.

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

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

States a specific verb (fetch), a single-resource scope (one customer) and the key identity key (Smile customer ID), which cleanly separates it from the sibling smile_list_customers. It also enumerates the returned fields, so an agent knows what it gets without opening anything else.

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?

Implicit usage is discernible: 'one customer by ... ID' versus the list siblings, and the optional include parameter is hinted at. However, no explicit when-to-use/when-not or named alternative is given, so the routing to smile_list_customers or smile_get_customer-adjacent tools is left to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description is not carrying the safety burden. It adds one useful behavioral detail beyond the annotations: the response includes the associated reward. Nothing is said about not-found behavior, permissions, or scoping.

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, key operation and scope front-loaded, with the API route appended as grounding for mapping to Smile docs. No filler or repetition.

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

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

For a one-parameter read with no output schema, the description covers the essentials and hints at the return payload ('including its reward'). It could say slightly more about what a points product contains or what is returned when the reward is absent, but nothing critical 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% and the single parameter (points_product_id) is fully documented in the schema, so nothing needs compensating. The description adds no format or constraint detail beyond 'by ID'. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch one points product ... by ID'), and the parenthetical defines the domain concept (a way to redeem points). The singular 'one ... by ID' implicitly separates it from smile_list_points_products, but no sibling is named explicitly, so it stops 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: an agent would infer this is for retrieving a single record when it already holds a points_product_id. There is no explicit when-to-use, when-not, or routing to alternatives such as smile_list_points_products or smile_purchase_points_product.

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

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

Annotations already provide readOnlyHint=true, so the safety profile is covered. The description adds the underlying API route (GET /points_transactions/{id}), which is minor context, but says nothing about 404 behavior, permissions, or response shape.

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

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

Two short sentences, front-loaded with the action and resource, with the API route as a compact reference. No wasted words.

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

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

For a simple one-parameter read tool with full schema coverage and a readOnly annotation, the description is sufficient to call it correctly. It could mention the list alternative or not-found behavior, but nothing essential is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema. The description adds no format or constraint detail beyond what the schema already provides, 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 (Fetch) and resource (one points transaction by ID), clearly distinguishing it from the sibling smile_list_points_transactions by emphasizing the single-item retrieval. It is clear but does not explicitly name the list sibling as an alternative.

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' wording implies this is for when you already know the transaction ID, but it never states when to use this versus smile_list_points_transactions or what happens if the ID is missing. Usage is only implied.

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

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

The annotations already declare readOnlyHint=true, and 'Fetch' is consistent with that. The description adds genuine value beyond the annotation by naming the exact fields returned (active status, advocate reward, friend reward) and the backing endpoint, though it omits anything about failure modes 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?

One tight sentence with the payload contents front-loaded and the endpoint appended. No filler or repetition of the title.

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

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

With no output schema and no parameters, the description carries the return-value burden and does so adequately by listing the configuration fields. It is complete for a simple read-only getter, with minor room to note error behavior or default state.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter claims are made or 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?

States a specific verb (Fetch) and resource (referral program configuration), then enumerates exactly what is returned: active flag plus advocate and friend rewards. An agent can distinguish this from sibling getters like smile_get_points_settings without opening a schema.

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

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

Usage is implied by the description — fetch this when you need referral program config — but there is no explicit when-to-use/when-not-to-use or reference to the closely related smile_get_points_settings sibling. A reader must infer the boundary themselves.

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 declare readOnlyHint=true, so safety is covered. The description still adds meaningful behavior beyond that: result ordering ('newest first'), cursor-based pagination with the specific metadata.next_cursor field, and the fact that email is an exact-match lookup. It omits rate limits and the default page size, but the added context is solid.

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-loaded with what is returned and how it is ordered, then how to filter, then pagination. Every clause carries information; nothing is redundant with the title.

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

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

For a 6-param list tool with no output schema, the description covers the essentials: returned fields, ordering, filter modes and pagination continuation. It leaves include_vip_status and the 1-250 limit default to the schema, which is acceptable, so it is nearly but not fully self-contained.

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

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

Schema description coverage is 100%, so the schema already documents email, limit, state, cursor, updated_at_min and include_vip_status. The description reinforces filtering semantics (exact email, state, last-updated) but adds no syntax or format 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 verb and resource ('List loyalty-program customers'), plus scope details like ordering ('newest first') and returned fields (points balance, state, VIP tier id). It is clearly distinct from the write/list siblings, but does not mention smile_get_customer, which is the natural alternative for a single-record fetch.

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 selection conditions: look up by exact email, or filter by state or last-updated time. That is clear usage context, but it never states when NOT to use this tool or routes the agent to smile_get_customer for single-customer reads, nor flags that email lookup is exact-match only (no fuzzy search).

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: only *enabled* rules are returned, the response carries reward/reward_value/earning_limit and VIP-tier restrictions, and results are cursor-paginated. This is meaningful added context for a read 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?

Three compact, front-loaded sentences: purpose and explanation first, then returned fields, then pagination and the underlying Smile endpoint. The parenthetical examples of earning types earn their place by making the resource concrete; nothing is wasted, though the field enumeration borders on redundant 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 compensates well by naming the key returned fields (reward, reward_value, earning_limit, VIP-tier restriction) and the pagination model. An agent can call this correctly with just the schema plus description; only the full response shape and permission requirements 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 description coverage is 100% — both 'limit' (1-250, default 50) and 'cursor' are fully documented in the schema, so the baseline is 3. The description only restates pagination ('Cursor-paginated') without adding format or edge-case detail 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?

States a specific verb and resource ('List the enabled earning rules') and explains what the resource actually is ('the ways customers earn points or rewards'), which is more than a restatement of the name. It does not explicitly differentiate itself from any sibling, though the sibling set is composed of unrelated resources, so confusion risk is low.

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: 'Cursor-paginated' hints at the multi-page retrieval pattern, and 'enabled' implies a filter over the full rule set. There is no explicit when-to-use guidance, no mention of prerequisites (e.g., API credentials), and no named alternative for retrieving disabled rules or a single rule.

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, so safety is covered. The description adds real value: it discloses pagination termination semantics ('a page shorter than page_size is the last'), states that each product embeds its reward, and explains the fixed/variable pricing mechanics — none of which appear in annotations or schema.

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

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

Four dense sentences, front-loaded with the resource definition followed by filter semantics and pagination. No filler, no restatement of the name, and the API endpoint hint is appended compactly at the end.

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

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

With no output schema, the description carries the return-value burden and handles it well, describing product structure, embedded rewards, and how to detect the last page. Only minor gaps remain (no auth/rate-limit note), which is acceptable given readOnlyHint covers the safety profile.

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 page and page_size are already documented (baseline 3). The description goes further by giving meaning to the exchange_type filter values, explaining that 'fixed' products cost points_price while 'variable' ones trade points per step within a min/max — semantics the enum alone does not convey.

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 (points products) and immediately defines the resource as 'the rewards customers can buy with points,' which distinguishes it from the singular smile_get_points_product sibling. An agent can tell what it returns without opening the schema.

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

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

Provides domain context on what points products are, but never states when to reach for this tool versus siblings like smile_get_points_product (single lookup) or smile_purchase_points_product. Usage is implied by the read-only list nature rather than made explicit.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value beyond that: newest-first ordering, cursor-based pagination, and the payload shape (points_change signed +/-, customer-visible description, merchant-only internal_note). It does not cover rate limits or page-size defaults, which the schema handles.

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 core purpose and scope before the parenthetical detail and pagination note. Dense and mostly waste-free, though the trailing 'Smile: GET /points_transactions' is implementation trivia of marginal value to an agent.

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 enumerates the returned fields and states ordering and pagination behavior. It omits any note on filtering behavior (e.g. what happens when customer_id is omitted) or result volumes, but it is sufficient 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 limit, cursor, customer_id and updated_at_min are fully documented in the schema (including the Smile default of 50 and ISO 8601 format). The description only alludes to pagination via 'Cursor-paginated' and adds no syntax or semantics beyond the schema, so the baseline 3 is correct.

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 points transactions') and defines scope precisely as 'every earn, spend and manual adjustment', newest first, plus a concrete use case (a customer's full points history). It implicitly distinguishes itself from the singular sibling smile_get_points_transaction, but never names a sibling explicitly, so it falls just short of 5.

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

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

The example ('a customer's full points history') implies when the tool is appropriate, and cursor pagination is disclosed, but there is no explicit when-to-use or when-not-to-use guidance and no routing to smile_get_points_transaction for single-record reads. Usage is only implied.

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?

readOnlyHint=true already establishes the safe-read profile, so the description only needs to add what annotations cannot. It notes the list is cursor-paginated and that records are "usually discount codes", but pagination is already covered by the cursor parameter description and there is no mention of auth scopes, rate limits, or ordering guarantees.

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: what the resource is, the fields returned, the key usage pattern, pagination behavior, and the backing endpoint. Nothing is redundant and the most important content is front-loaded.

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

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

With no output schema, the description compensates by naming the returned fields, and it flags pagination for a 6-parameter list endpoint. Only a note on default ordering/date scoping (updated_at_min) would make it fully self-sufficient.

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

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

Schema coverage is 67%, so the schema handles most of the burden, but the description adds practical meaning to customer_id (answering "what codes does this customer have?") and frames fulfillment_status/usage_status alongside their observed values. limit, cursor, and updated_at_min are 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 ("List rewards that have been issued to customers — usually discount codes") and even enumerates the returned fields (code, fulfillment_status, usage_status, used_at, expires_at). No sibling tool covers reward fulfillments, so there is no ambiguity to resolve.

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

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

Provides a concrete usage pattern: "Use customer_id to answer 'what codes does this customer have?'", which tells the agent when this tool is the right call. It stops short of stating when-not to use it or naming an alternative path, but the context is clear.

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

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

readOnlyHint=true already covers the safety profile, so the description's remaining duty is extra behavior. It usefully discloses the default sort (by milestone threshold) and that nested perks/entry rewards are opt-in, but says nothing about pagination, result limits, 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?

One compact sentence with the resource, sort order, and optional inclusion all front-loaded; the API endpoint reference is short and non-redundant. No wasted words.

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

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

For a simple zero-required-param read tool with no output schema and full schema documentation, the description covers the essentials. It only lacks minor operational detail like pagination behavior, which is a small gap at this complexity.

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 enum-array param is fully documented in the schema. The description restates the include purpose ('optionally with each tier's perks and entry rewards') but adds no format or defaulting nuance beyond the schema. 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 the VIP program's tiers') and adds distinguishing scope detail: sorting by milestone threshold and optional nested data. No sibling overlaps with VIP tiers, so an agent can identify this tool's job immediately.

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 description (fetch the tier list, optionally with nested data) but there is no explicit when-to-use/when-not, no prerequisites, and no named alternative. Adequate but leaves routing to inference.

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

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

Annotations already flag destructiveHint=true, and the description goes well beyond that: it discloses that points are spent/deducted, that the reward is issued via the response's points_purchase.reward_fulfillment, that there is no cancellation API, and that the points_purchase:write scope is required. This is exactly the additional context the annotation does not carry.

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

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

Front-loads the critical WRITE/SPENDS warning, then layers conditions, failure semantics, and scope in compact clauses. No sentence is filler; the density is warranted by the tool's risk profile.

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 destructive write tool with no output schema, the description covers safety (irreversible), auth (scope), branching logic, and even a hint at the response shape (discount code in reward_fulfillment). Nothing an agent needs to invoke it safely 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 the baseline is 3. The description adds real conditional meaning: points_to_spend is required only for 'variable' products and must be omitted for 'fixed' products, which the schema's flat per-parameter text does not convey. Customer and product ID semantics are left 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 precise verb and resource — redeem points by purchasing a points product — and immediately distinguishes its effect ('Smile deducts the points and issues the reward'). An agent can tell it apart from read-side siblings like smile_get_points_product or smile_list_points_transactions without opening a schema.

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

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

Explicitly states when to use it ('Only do this when the customer asked for it'), how to branch on product type ('pass points_to_spend for variable, leave it out for fixed'), and names the alternative path when something goes wrong ('can only be compensated with smile_create_points_transaction'). All the decision conditions are spelled out.

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