foxyio

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

Beyond the readOnlyHint annotation, the description discloses the HTTP endpoint (GET /) and the response nature: a home document containing _links/rels, including fx:store. This adds meaningful behavioral context about what the call returns without contradicting the 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?

Two tight sentences with no filler. The core resource and key response detail come first, and the endpoint hint is placed at the end without waste.

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 no-parameter, read-only discovery call, the description is complete: it names the endpoint, identifies the response shape, highlights the most relevant relation, and states the use case. No essential invocation detail is missing, and the 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?

There are zero parameters, so there is no parameter semantics burden. The schema coverage is 100% and the description adds relevant context about the endpoint, earning the baseline of 4 for a parameterless tool.

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 precisely states the resource (Foxy hAPI home document), the verb (GET), and the specific content (_links/rels including fx:store). This clearly differentiates it from sibling get/list tools by framing it as the HAL discovery entry point rather than a resource 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?

It gives a clear use case ('useful for HAL discovery') and notes the fx:store relation for the authenticated default store, which tells the agent when to reach for this tool. It does not explicitly contrast it with alternatives like foxy_get_default_store or foxy_get_store, but the discovery framing makes the usage context 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?

The readOnlyHint annotation already establishes this as a safe read operation. The description adds useful behavior beyond that: it names the HTTP endpoint (GET /customers/{id}) and documents the optional 'zoom' behavior that embeds related resources.

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 with no filler. The core action is front-loaded, and the endpoint reference is brief and informative.

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 single-resource read tool, the description plus annotations and complete schema coverage are nearly sufficient. It does not explicitly describe the return payload, but no output schema exists and the GET endpoint strongly implies the customer object is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete zoom examples (default_billing_address, subscriptions…) and clarifying the request format via the endpoint, going slightly 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?

Description states a specific verb and resource: 'Get a single customer by id'. The qualifier 'single' and reliance on an id clearly distinguish it from sibling list tools, and the optional zoom behavior adds further precision.

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?

Clear usage context is provided: use this to fetch exactly one customer by id. It does not explicitly name alternatives like foxy_list_customers for bulk retrieval or foxy_update_customer for mutations, but the contrast is strongly implied by 'single... by id'.

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

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

Beyond the readOnlyHint annotation, the description reveals that the tool performs a multi-step operation: fetching the API home then following the fx:store link via GET. This explains the underlying HTTP calls and the indirection involved, which is useful behavioral context not present in the schema or 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?

Three concise sentences with no filler. The main action is front-loaded, followed by practical usage guidance and the underlying HTTP route. Every sentence earns its place.

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

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

For a zero-parameter, read-only discovery tool, this description is complete. It explains what the tool returns, why an agent would call it, and how the resolution works internally, so an agent can invoke it correctly without additional context.

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 has zero parameters and the schema is fully covered, so schema-level semantics are trivially complete. The description adds value by explaining what the result contains (the default store and its id) and how that result should be used.

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 action ('Resolve and return the authenticated user's default store (and its id)') and names the resource. It clearly distinguishes itself from sibling tools like foxy_get_api_home and foxy_get_store by focusing on the default store rather than any arbitrary store.

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 explicitly says to use this tool to discover the store_id that list tools accept, giving clear actionable context. It does not explicitly state when not to use alternatives like foxy_get_store or foxy_get_api_home, but the intended role before list operations 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?

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds value by disclosing that the response includes settings and _links to sub-collections, which goes beyond the annotation and helps the agent anticipate the returned structure.

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 carry meaningful information: the first describes the action and return contents, the second identifies the exact endpoint. There is no wasted text, and the core purpose 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?

For a simple read-only single-resource tool with one well-documented parameter, the description is largely complete. It states what is returned (store resource, settings, _links) and the endpoint; a brief note on possible failure behavior or absent fields would be the only minor improvement.

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 for the single required parameter is 100%, with the store_id description pointing to foxy_get_default_store as the source. The tool description adds no new parameter-level semantics, but the schema already handles it fully, so a 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?

The description states a specific verb ('Get'), a single resource ('a single store resource by id'), and what is included ('settings and _links to sub-collections'). This clearly differentiates it from sibling list and update tools, and the hAPI endpoint reinforces the exact REST operation.

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 clearly implies this tool is for fetching a specific store by ID when you already have that identifier. It does not explicitly name alternatives or say when not to use it, but the 'by id' scope and sibling context make the usage situation reasonably 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?

The readOnlyHint annotation already declares this is a read operation, and the description aligns with that by using 'Get'. It adds the useful behavioral detail that related resources can optionally be embedded via 'zoom', but it does not disclose behavior like not-found responses or how zoom affects the payload beyond what the schema hints.

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, no filler. The core purpose ('Get a single subscription by id') is front-loaded, and the endpoint reference provides useful context without bloating the text.

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

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

For a simple read tool with only two parameters, this is largely complete: it names the resource, the identifying parameter, the optional zoom behavior, and the underlying endpoint. It does not describe return shape or error cases, but the readOnlyHint and straightforward GET semantics make this 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?

The schema already covers both parameters with descriptions, so the description is not required to add much. The phrase 'optionally zooming related resources' loosely maps to the zoom parameter, but it adds no extra meaning beyond the schema's own description and example.

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 ('Get'), a specific resource ('a single subscription'), and the selection mechanism ('by id'), clearly distinguishing it from foxy_list_subscriptions and foxy_update_subscription. The mention of optional 'zoom' behavior further clarifies its scope.

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 clearly implies this tool is for retrieving one subscription by its id, and the context of the Foxy hAPI endpoint reinforces that. It does not explicitly name alternatives like list_subscriptions or update_subscription, but the single-resource framing gives enough context for an agent to choose it over listing or updating.

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 read-only nature is covered. The description adds the GET endpoint and the optional zoom behavior, but it does not go much deeper with response format, error cases, or other behavioral details, which keeps this at a solid but not exceptional level.

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

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

The description is two short, purposeful sentences. It front-loads the main action and unique selector, then gives the endpoint and zoom behavior; there is no filler or redundant restatement 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 fetch with fully documented parameters and a readOnlyHint annotation, the description covers everything needed to call it correctly: the transaction id, the optional zoom behavior, and the underlying API route. No output schema exists, but 'get a single transaction' sufficiently conveys the expected result.

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 both id and zoom are documented. The description adds extra concrete examples of zoomable resources (payments, applied_taxes) beyond the schema's 'items,customer', giving the agent more useful value without contradicting 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 description clearly states the action ('Get'), the resource ('single transaction'), and the selector ('by id'), which distinguishes it from foxy_list_transactions and other foxy getters. The optional zoom note adds useful scope without blurring the core 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?

The description makes the context clear: use this when you have a transaction id and need one transaction, optionally with embedded related resources. It does not explicitly name alternatives like foxy_list_transactions for discovery, so it stops short of a 5, but the intended use is not merely 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?

Annotations declare readOnlyHint=true, and the description adds value beyond that by specifying the return shape: 'a HAL collection embedding fx:carts' and the exact HTTP endpoint. It does not cover pagination details, but the parameter schema already documents limit and offset.

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

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

The description is two sentences with no filler. The main action and resource are front-loaded, and the parenthetical clarification plus endpoint reference add useful information without bloat.

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

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

For a read-only list operation with all parameters fully described in the schema, the description provides the essential context: the resource, its conceptual meaning, the HTTP endpoint, and the HAL response format. There is no output schema, but the return type is explicitly stated.

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 parameter schema fully documents zoom, limit, offset, and store_id. The description itself adds no additional parameter semantics beyond the endpoint path, which reflects the store_id but not the other parameters.

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

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

The description states a specific verb and resource: 'List a store's carts' and clarifies the resource as 'in-progress / abandoned checkouts'. It also references the exact Foxy hAPI endpoint, which makes the operation unambiguous and distinguishes it from the sibling list tools.

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

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

The description gives clear context: this is the tool for listing carts belonging to a store. It does not mention exclusions or alternative tools, but no sibling tool directly competes with this cart-listing operation, so the context is sufficient.

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?

While readOnlyHint already signals the read-only nature, the description goes further by disclosing the exact return shape (HAL collection embedding fx:coupons) and the underlying HTTP endpoint. This gives an agent expectations about the response format without an output schema. It does not detail pagination behavior, but the readOnlyHint combined with response details covers the key behavioral characteristics.

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 concise sentences lead with the purpose, then provide response format and endpoint. There is no filler, and the most decision-relevant information 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?

For a read-only list operation with fully documented parameters and no output schema, the description is complete. It names the resource, scope, response container (HAL + fx:coupons), and the HTTP endpoint, so an agent has everything required to invoke and interpret the result. The lack of a separate output schema is mitigated by the response format hint.

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

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

Schema description coverage is 100%, with all four parameters fully documented in their property descriptions. The tool description adds no parameter-level semantics beyond the schema. Baseline 3 applies because the schema already does the heavy lifting.

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

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

The description opens with a specific verb and resource, 'List a store's coupons', and clarifies that coupons mean discount codes and their rules. This separates it from sibling list tools (carts, customers, items, subscriptions, transactions) purely by resource. No ambiguity about what operation this performs.

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 tool's scope is clearly contextualized as reading a store's coupons, which is sufficient because no same-resource sibling exists. It does not explicitly name alternatives or exclusion conditions, but it is obvious from the resource-oriented description when this list tool is appropriate.

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 readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context by disclosing the HAL collection response shape and the exact GET endpoint. It does not contradict the annotation and provides value beyond the structured metadata.

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

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

The description is three short sentences, each earning its place: purpose, return format, and API endpoint. It is front-loaded with the core action and contains no filler or redundant restatement 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 operation with no required parameters, the description covers purpose, response representation, and endpoint. Pagination and default store behavior are already documented in the schema, so the definition is largely complete, though it could briefly mention when filtering by email or pagination is relevant.

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 four parameters are already fully documented in the input schema. The description adds no additional parameter-level meaning beyond what the schema and endpoint path convey, so the baseline of 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?

The description states a specific verb and resource: 'List a store's customers,' and notes it returns a HAL collection embedding fx:customers. It is clear, but it does not explicitly differentiate itself from the sibling foxy_get_customer beyond the plural resource and collection format.

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 provides no guidance on when to use this tool versus alternatives such as foxy_get_customer or foxy_update_customer. There are no exclusions, prerequisites, or routing conditions, leaving the agent to infer usage from the tool name and siblings.

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

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

Beyond the readOnlyHint annotation, the description discloses the response shape ('Returns a HAL collection embedding fx:items') and the API contract. It does not explain HAL pagination semantics or zoom behavior, but the schema covers pagination parameters and readOnlyHint covers safety.

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, both informative: the first defines the resource, the second specifies return format and endpoint. No filler or redundant restatement 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?

Complete for a simple read-only list tool: the resource, response format, endpoint, and parameters are all covered. The readOnlyHint covers side-effect expectations, and no output schema is needed given the explicit HAL collection description.

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

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

Schema coverage is 100%, so all four parameters are already documented. The description adds minimal parameter meaning beyond 'transaction_id' via the endpoint path and 'products purchased' context, but it does not need to compensate for schema gaps.

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'), resource ('line items of a transaction'), and disambiguating parenthetical ('the products purchased'). It also provides the exact hAPI endpoint, making it clearly distinct from siblings like foxy_get_transaction and foxy_list_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?

The description makes the tool's scope clear: list items for a single transaction. It does not explicitly name alternate tools or state when not to use it, but the sibling list and endpoint path give sufficient context for an agent to route correctly.

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 mark readOnlyHint true; the description adds that it returns a HAL collection embedding fx:subscriptions and uses GET, confirming no side effects and disclosing response shape. It doesn't cover pagination behavior beyond params, but that's minor.

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?

Single sentence front-loads action and resource, then supplies return format and endpoint; 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?

For a simple list tool with no required params and full schema coverage, the description gives the key context (store-scoped collection, HAL format, GET endpoint). It doesn't explicitly mention pagination or default store, but those are in the schema, so 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%, so the schema fully documents all five optional parameters. The description adds no parameter-specific meaning, which is acceptable at 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 the verb 'List' and resource 'a store's subscriptions' with clarifying 'recurring orders,' distinguishing it from foxy_get_subscription and foxy_update_subscription. Also names the exact endpoint and return collection rel.

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 list vs. resource-scoped name, and the endpoint clarifies it is a collection read. However, it does not explicitly say when to prefer foxy_get_subscription for a single subscription or exclude update scenarios, so an agent must infer the fit.

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 readOnlyHint annotation already discloses that this is a safe read operation. The description adds value by specifying the default order ('newest first'), the output shape ('Returns a HAL collection embedding fx:transactions'), and the exact REST endpoint, none of which are present in the annotations or schema.

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

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

Two concise sentences front-load the core purpose ('List a store's transactions... newest first') and then add efficient supplementary details about return format and endpoint. There is no redundant or filler content.

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

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

For a read-only list operation, the combination of schema (100% parameter coverage), annotations (readOnlyHint), and the description's output shape, ordering, and endpoint fully equips an agent to invoke it. No output schema exists, but the description names the HAL collection return type, covering the main missing piece.

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 seven parameters are already documented, giving a baseline of 3. The description does not add specific parameter-level semantics beyond the schema's own descriptions, though it does state the default ordering that the 'order' parameter can override.

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 uses a specific verb and resource: 'List a store's transactions (orders)', and adds the ordering 'newest first'. It clearly identifies the target entity as transactions, distinguishing it from sibling list tools for carts, coupons, customers, etc.

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 implies use when listing a store's transactions, and the endpoint confirms the resource, but it does not explicitly state when to prefer this over alternatives such as foxy_get_transaction for a single record or other list tools. There is clear context, but no exclusions or alternative 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?

The annotations already declare destructiveHint=true, and the description reinforces this by stating 'This MODIFIES live store data,' adding the production-impact context beyond the raw flag. 'Provide only the fields you want to change' also discloses partial-update behavior, which is meaningful and not present in the structured metadata.

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 contain the purpose, the live-data warning, the endpoint reference, and the key usage instruction. Every clause earns its place, and the most important information 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?

For a four-parameter update with no output schema, the description covers the essential operational aspects: what is updated, that it is a PATCH to /customers/{id}, the destructive nature on live data, and the partial-update rule. It lacks details such as idempotency or error handling, but these are not critical for correct invocation.

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 value by clarifying the PATCH semantics—'Provide only the fields you want to change'—which tells the agent that optional params can be sent individually and omitted fields are preserved. This is important behavioral nuance beyond the schema's 'New ...' descriptions.

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 'UPDATES a customer's profile fields' and explicitly lists first_name, last_name, and email, making both the verb and resource precise. This clearly differentiates the tool from the read/list siblings and from update_subscription by targeting the customer resource.

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

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

'Provide only the fields you want to change' gives clear, actionable guidance for the PATCH-style partial update, and the warning 'This MODIFIES live store data' sets expectations for when to invoke it. It does not explicitly name alternative tools or exclusions, but the context is unambiguous enough that an agent can select it correctly.

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 destructiveHint=true, and the description adds meaningful context: it modifies live store data, affects future billing, uses PATCH /subscriptions/{id}, and supports partial updates. This goes beyond the annotation without contradicting 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?

The description is concise and front-loaded with the action and resource. It packs the endpoint, the modification semantics, the business impact, and the partial-update guidance into two efficient sentences 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?

Given the 4-param schema with full coverage, the destructive annotation, and the clear endpoint, the description is substantially complete for correct invocation. It lacks details about the response shape or error cases, but those are not critical for selecting and calling this update tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a few semantics by linking next_transaction_date to rescheduling and is_active to activate/pause, plus clarifying that only desired fields should be passed, but it doesn't heavily extend 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 description states a specific verb ('UPDATES') and resource ('a subscription'), and enumerates the exact operations: rescheduling next run, changing frequency, and toggling active state. It clearly distinguishes this from the sibling foxy_update_customer and from read-only subscription 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?

The description provides clear context for when to use this tool — when modifying a subscription's schedule, frequency, or active status — and includes the important guidance to provide only fields to change. It doesn't explicitly mention alternatives or when-not-to-use, but the context is clear enough.

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