Gift Up! MCP by usefulapi

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 that the resource is scoped to the requesting API key and lists the data exposed, which is modest additional context but nothing about auth failures, caching, or rate limits.

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: the returned fields are front-loaded and the endpoint is tacked on at the end as a routing aid. 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 present, the description takes on responsibility for describing return values and does list the key fields, which is enough to call the tool correctly. It is slightly incomplete in not confirming the response envelope or error modes, 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?

The tool takes zero parameters, so the baseline is 4. The description instead documents the output shape (id, name, currency, onboarding status, checkout status), which is the only meaningful 'semantic' content for this call.

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?

Identifies a specific resource (the Gift Up account tied to the calling API key) and enumerates the returned fields, so it is clearly distinct from the sibling tools that deal with gift cards, items, orders, and transactions. The verb is only implied via the title/endpoint rather than stated, keeping it just 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 implied by the singleton nature of the endpoint (account-level lookup, no filters), but there is no explicit statement of when to reach for this versus other get_* tools or any prerequisite framing beyond the API-key scoping.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is partly covered; the description still adds real value by asserting it 'never redeems or changes the card' and by warning that the full code is echoed back and should not be repeated elsewhere. That data-handling caution is not derivable from 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?

Two dense sentences: the first enumerates the payload, the second handles the sensitive-return warning and the read-only guarantee, and the route is appended last. Nothing is padded and the load-bearing 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 usefully inventories the response (balance fields, status flags, expiry, recipient, order, fulfilment, event ledger), which is exactly what an agent needs to consume the result. It stops short of noting error behavior for an unknown code or how the ledger is ordered, but is otherwise complete for a single-resource read.

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% with only two simple params (code, test_mode), so the schema carries the parameter burden. The description adds nothing about test_mode's test-vs-live data semantics or code format beyond what the schema states, which is the expected baseline-3 case.

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 ('one gift card by its code') and enumerates the returned facets (balance, status, expiry, recipient, order, fulfilment, ledger). The singular framing clearly distinguishes it from the sibling giftup_list_gift_cards, and the raw route GET /gift-cards/{code} pins the contract.

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: you call this when you already hold a code, versus listing when you don't. There is no explicit when-not statement or named alternative, and no guidance on how to recover from an invalid/unknown code, so the guidance stays at the implied level.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld). The description adds genuinely useful behavior beyond that: pre-generated codes are collapsed to a count with masked tails, which tells the agent the returned payload is transformed rather than raw. The GET endpoint path is also disclosed.

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 fragments with zero filler, and the core identity (what item is) is front-loaded. Slightly telegraphic but nothing wasted.

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

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

No output schema exists, so the description carries some return-value burden; it does disclose the notable code-masking behavior, which is the main surprise in the response. It stops short of describing the item's other fields, but for a simple single-resource getter this is close to 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%, so both item_id (GUID from giftup_list_items) and test_mode are already fully documented in the schema. The description adds only 'by id', which the schema already conveys, 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 (Get) and resource (item, clarified as 'gift card product') by id. The parenthetical disambiguates 'item' from the sibling giftup_get_item_group, and 'by id' distinguishes it from giftup_list_items.

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

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

There is no statement of when to use this tool versus giftup_list_items or giftup_get_item_group, and no prerequisites or exclusions. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds nothing beyond restating the underlying GET endpoint, so a lower score is warranted despite the lighter burden annotations create.

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 fragments, front-loaded with the core purpose. The trailing 'GET /groups/{id}' is somewhat redundant but costs little and confirms the operation type.

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 GET with full schema coverage and no output schema, the description is adequate but minimal. It omits any note on the test_mode toggle's effect or expected return shape, though the schema carries most of that.

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 group_id and test_mode are fully documented in the schema. The description contributes no additional parameter meaning, making the baseline 3 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 resource and scope ('One item group by id'), which distinguishes it from the plural sibling giftup_list_item_groups. The verb is implied by the tool name rather than spelled out, but the intent is unambiguous.

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

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

The description offers no when-to-use guidance or mention of alternatives. The only hint at workflow ('from giftup_list_item_groups') lives in the schema's parameter description, not the description itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds that this is a GET /orders/{id} read and hints at return breadth, but says nothing about auth requirements, error behavior for a missing/invalid id, or rate limits.

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 resource and identifier front-loaded; the field list is dense but informative and the endpoint reference is a useful anchor. Slightly telegraphic but no wasted sentences.

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 the annotations carry the safety profile. Missing only the when-not-to-use routing and any error/permission context, which is minor for a simple id-based read.

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% (order_id is documented as a GUID sourced from giftup_list_orders, test_mode explains the x-giftup-testmode header and default). The description only re-states 'by id' and adds no format or edge-case detail, so the schema does the heavy lifting and 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+resource ('One order by id') and enumerates the payload it returns (totals, purchaser, promotions, taxes, notes, payment provider). The 'by id' scoping implicitly separates it from giftup_list_orders, though it never names the 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: single-record retrieval keyed by id versus the sibling list tool. There is no explicit when-to-use statement, no mention of prerequisites, and no named alternative such as giftup_list_orders for bulk lookup.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the gift card code returned is MASKED with at least 6 characters hidden, which an agent could not learn from the structured fields.

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

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

Three short fragments with no waste, and the core purpose is front-loaded. The telegraphic style (fragments rather than sentences) is efficient, though slightly clipped.

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

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

For a read-only single-resource getter with no output schema, the definition covers the key gotcha (masked gift card code) that would otherwise confuse an agent. Return structure is not described, but that is the only notable 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 both parameters (transaction_id GUID, test_mode toggle) are fully documented in the schema. The description adds no parameter-level detail, 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 ('One report transaction by id'), which is clearly distinct from the sibling list tool giftup_list_transactions. It is clear but does not explicitly name the sibling it differs from, keeping it just 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?

There is no explicit when-to-use guidance or mention of alternatives. The id-based retrieval is implied by the description, but the agent must infer that list_transactions is the counterpart for bulk retrieval rather than being told.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds non-obvious behavior the annotations cannot convey: codes are MASKED with at least 6 characters hidden, which materially affects how an agent should use the results. It does not discuss pagination or result caps beyond 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?

Three sentences, front-loaded with what is returned and the masking caveat before the pointer to the sibling tool. Dense but every clause carries information; the trailing endpoint note is the only 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 11 optional params, no output schema and no required fields, the description compensates by describing the shape of the returned records and the masking behavior. It omits pagination guidance, though the schema's offset description covers next_offset, leaving only a minor 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 with length, pattern and enum constraints. The description restates the filter dimensions (state, creation/update time, order, SKU, recipient/purchaser email, transaction id) without adding format or edge-case meaning 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 gift cards') and immediately enumerates the returned fields (balance, status flags, title, recipient, expiry, originating order). It also explicitly distinguishes itself from the sibling giftup_get_gift_card, which returns a single card in full.

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?

Names the alternative tool and the exact condition that selects it: 'to see one card in full (code and ledger) use giftup_get_gift_card with its code.' It also enumerates the filter axes available here, telling the agent what this tool is for.

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 list and the GET endpoint, which is genuinely useful context, but says nothing about pagination, result limits, or the test-mode toggle's effect — so it clears the lowered bar without exceeding it.

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

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

A single front-loaded sentence that names the resource, defines it, enumerates return fields, and cites the endpoint. No filler, though the trailing 'GET /groups' is decorative rather than actionable.

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 inline enumeration of returned fields (id, name, description, sort order, auto-expand) usefully compensates and tells the agent what to expect. The tool is simple and parameter-light, so the omission of pagination details is a minor 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?

Only one optional parameter (test_mode) and schema description coverage is 100%, so the schema fully documents it. With that baseline of 3, the description adds no parameter-level meaning 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 clear verb+resource (list item groups) and immediately disambiguates the domain concept with a parenthetical ('the sections that organize items in the checkout'). The list_ prefix plus the returned-field enumeration separates it from giftup_get_item_group and giftup_list_items, though no sibling is named 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?

Usage is implied by the read-only 'List ... GET /groups' framing, but the description offers no explicit when-to-use, no statement of when to prefer giftup_get_item_group, and no mention of when test_mode should be set. The agent must infer selection from naming conventions 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 cover readOnly, openWorld, and non-destructive behavior, so the bar is low, yet the description adds real context: pre-generated codes are collapsed to a count with masked tails, and results include availability window and stock level. It does not mention pagination or whether all items are returned at once.

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

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

Front-loaded with the verb and resource, then a dense but useful field enumeration, ending with the GET /items hint. The long field list is justified because there is no output schema, though it is slightly run-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 no output schema, the description usefully enumerates the returned fields including the special masking behavior for pre-generated codes. Both optional parameters are at least gestured at, though test_mode semantics and result-set size/pagination are left 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%, so both group_id and test_mode are already documented at baseline. The description's 'Optionally only one group' adds slight flavor for group_id but says nothing about test_mode, so no credit above 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 ('List the gift card products on sale (items)') and disambiguates the API's 'items' terminology, which is helpful against siblings like list_gift_cards and list_item_groups. It does not explicitly contrast itself with get_item/list_item_groups, 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?

The only guidance is 'Optionally only one group,' which hints at the group_id filter but never says when to use this list versus get_item, get_item_group, or list_gift_cards. No context, prerequisites, or conditions for choosing this tool 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the ids are used to filter/label transactions and that the endpoint is GET /locations, but says nothing about return shape, ordering, or pagination.

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, front-loaded with the action and resource, and each clause (stores gloss, id purpose, endpoint) carries information. No filler or repetition of the title.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the description covers purpose, endpoint, and the significance of the returned ids. Only a brief note on what each location record contains 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 description coverage is 100% and the single optional test_mode parameter is fully documented in the schema (including the x-giftup-testmode header behavior and default). The description adds no parameter detail, 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 the locations (stores) of the account") and clarifies what a location is via the "(stores)" gloss. It also distinguishes this resource from the surrounding get_*/list_* siblings by explaining the downstream role of the returned ids (filtering and labeling report 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?

Usage is only implied: the clause about ids filtering and labeling report transactions hints at why an agent would call this first, but there is no explicit when-to-use, when-not, or named alternative among the sibling tools. Adequate but leaves the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine context beyond that: results are ordered newest first, the shape of each record (revenue, tip, fees, promotions, metadata, payment provider), and the underlying GET /orders endpoint. It does not describe pagination semantics, though the schema's offset description carries that.

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

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

One dense but well-ordered sentence: purpose and parenthetical definition first, then returned fields, then filter options, then the endpoint. The field enumeration is long but each item informs the agent about available data; no filler sentences.

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

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

With no output schema, the description correctly compensates by listing the fields each order returns, and annotations carry the safety profile. Pagination and filtering mechanics live in the schema, so nothing critical is missing, though the list of record fields is illustrative rather than exhaustive.

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 six parameters including the source enum and test_mode flag are already fully documented. The description echoes three of the filter dimensions (creation time, purchaser email, source) but adds no format or syntax details 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?

The description states a specific verb+resource ('List orders') and immediately disambiguates the domain term ('the purchases that created gift cards'), which distinguishes it from the singular sibling giftup_get_order. It also enumerates the returned fields and the default sort order, so an agent knows exactly what it gets back.

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: 'Filter by creation time, purchaser email or source' hints at the retrieval scenario, and listing multiple orders implicitly contrasts with giftup_get_order for a single order. There is no explicit when-to-use/when-not statement or named 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered; the description's 'Read-only' is consistent though redundant. It does add value beyond annotations by naming the backing endpoint and by surfacing the shape of the returned data (dates, benefits, usage counts, revenue, triggers), which is meaningful given 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?

A single dense sentence that front-loads the core action and then the returned fields, followed by a short read-only/endpoint note. Every clause carries information, though the long parenthetical field list is slightly list-heavy rather than 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?

With no output schema, the description compensates by describing the returned promotion structure (name, dates, benefits, usage/revenue, limitations, triggers), which is what an agent needs to interpret results. Minor gaps remain: no mention of pagination or result limits, and nothing about how test_mode affects 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?

There is one optional parameter (test_mode) and schema description coverage is 100%, so the schema already fully documents it. The description adds no parameter-level detail (e.g., that test_mode data is isolated from live revenue figures), 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+resource ('List promotions') and immediately clarifies scope with the parenthetical 'checkout discounts and bonus credit', which disambiguates the term 'promotion' from marketing/other concepts. It also enumerates what each promotion contains (dates, benefits, usage, limitations, triggers), so an agent knows exactly what this returns versus the sibling get_* 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?

Usage is only implied: it lists promotions and notes 'Read-only. GET /promotions.' There is no explicit guidance on when to use this versus giftup_get_order or giftup_list_transactions (e.g., 'use this to find a promo code before an order lookup'), nor any exclusions or prerequisites.

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 genuinely new behavioral context: the log is immutable, and gift card codes are masked (at least 6 characters hidden), which is important for interpreting results. It does not discuss pagination limits beyond what the schema's offset/limit already 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?

The log definition and event enumeration are front-loaded, followed by masking and filter information, with no filler sentences and the endpoint appended. The event-type enumeration is long but earns its place by mapping to the events enum and the semantic content of each event.

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

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

With no output schema, the description does the work of explaining what a returned record contains (who, where, reason, Gift Up fee, and the value change) plus the masking guarantee, which is what an agent needs to interpret results. It stops short of describing pagination response fields like next_offset.

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 the schema, making baseline 3 appropriate. The description restates the filter dimensions and notably clarifies that only one gift card code can be supplied, which is a minor addition over 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 (List) and resource (transactions) and defines exactly what a transaction is: the immutable financial event log, enumerating OrderPlaced, GiftCardCreated, Redeemed, Voided, etc. An agent can distinguish this from the singular giftup_get_transaction and from order/gift-card tools 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?

The description names the available filters (time range, event type, user email, location id, one gift card code), which implies the report-query use case, but it never states when to prefer this over giftup_list_orders or giftup_get_transaction, nor any exclusions or prerequisites. Usage is inferable 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.