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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds valuable nuance beyond them: the operation is reversible, restoration happens via the dashboard (not via an API sibling), and the current offering is excluded. This is meaningful behavioral context, though it doesn't address effects on existing subscriptions or entitlements.

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, zero filler, with the core semantics (hide, not delete) front-loaded and the constraint appended. Every clause carries information.

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

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

For a simple two-parameter, no-output-schema mutation with annotations present, the description covers the key question (reversibility, scope limitation). Minor gaps remain around side effects on active subscriptions, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so both offering_id and the optional project_id are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (hides/archives) and resource (offering), and immediately distinguishes the action from deletion by noting it can be unarchived. An agent can tell this apart from a delete-style sibling 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?

Gives clear context for when to use it (hide an offering from apps while preserving it) and states an explicit precondition: the current offering cannot be archived. It doesn't name a named alternative tool, but the use case is unambiguous.

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=false, idempotentHint=true and destructiveHint=false, so the mutation/safety profile is covered structurally. The description adds the semantic effect (products unlock an entitlement) worth some credit, but says nothing about the 50-item limit, permission requirements, or what happens to products already attached.

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 effect and then the operational guidance, with 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 needed, 100% schema coverage, and annotations carrying the safety profile, the description is nearly sufficient. It leaves minor gaps around the collection size ceiling and error behavior on unknown entitlement/product ids.

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, and the description earns a bump by explaining the intended content of product_ids — one product per store (iOS, Android, Test Store) rather than an arbitrary set. That is meaning the schema's terse 'Product ids (prod...)' 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+resource ('Makes products unlock an entitlement') and clarifies the effect on entitlements, which distinguishes it from sibling attach-products-to-package even if that sibling is not named. Clear enough to select correctly.

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 second sentence gives contextual advice ('Attach every store's version of a plan (iOS, Android, Test Store)'), which implies when this tool is used. However, it never names the near-identical sibling attach-products-to-package or states an exclusion, so the agent must infer which tool applies.

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 disclose readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a useful behavioral constraint ('at most one per app') and an example, but does not explain what happens on conflicts, whether existing attachments are replaced, or required permissions.

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 states the operation, the main constraint, and a concrete example without any filler. Every element earns its place and helps an agent understand the action quickly.

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

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

For a 4-parameter mutation with rich schema coverage and annotations, the description supplies the core purpose and a uniqueness constraint. However, it omits usage guidance relative to the entitlement sibling and does not describe conflict or replacement behavior, leaving some gaps 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 schema fully documents package_id, project_id, product_ids, and eligibility_criteria. The description adds no parameter-level detail beyond the schema and only illustrates the product_ids concept indirectly through the monthly-products 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?

States a specific verb and resource ('Puts products in a package') and adds a key constraint ('at most one per app') plus a concrete example. It distinguishes itself from the entitlement sibling by operating on packages rather than entitlements, though it does not explicitly name the alternative tool.

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

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

The description explains what the tool does but gives no guidance on when to use it versus attach-products-to-entitlement, no prerequisites, and no indication of when not to use it. Usage is only implied by the operation 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 destructive=true and idempotent=false, and the description goes well beyond them by disclosing deferred timing (access retained until period end), store-dependent support with an explicit error response for unsupported stores, and a required user-confirmation step. This is exactly the behavioral context an agent needs before invoking a destructive write.

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

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

Three short sentences with the most decision-relevant fact (deferred cancellation) front-loaded, followed by the support constraint and the safety instruction. 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?

For a two-parameter destructive mutation with no output schema, the description covers timing semantics, platform support bounds, error behavior, and the confirmation requirement. Nothing an agent needs to call 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 description coverage is 100%, so both parameters are already documented in the schema. The description adds no parameter-level syntax or format guidance, so the baseline of 3 applies.

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

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

States a specific verb and resource plus a non-obvious scope detail: cancellation takes effect at the end of the paid period, not immediately. That timing nuance distinguishes it from siblings like refund-subscription and extend-subscription without needing to name them.

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

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

Gives clear context: it only works where the store permits server-side cancellation (e.g. Google Play), and it explicitly instructs the agent to confirm with the user first. It does not name alternatives (e.g. refund-subscription for immediate revocation), so it falls short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: credentials are not configured here but in the dashboard, and a follow-up call to list-public-api-keys is needed. It does not disclose failure modes (duplicate names, invalid bundle_id) or what the response contains.

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

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

Two sentences, both front-loaded and purposeful: the first defines the variants, the second removes a false assumption (credentials) and points to the next step. 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?

With 100% schema coverage and no output schema, the description carries only the workflow burden, and it does that well by routing the agent to the credential dashboard and the API-key listing. Minor gap: no mention of duplicate-name behavior or project_id scoping nuance, though the latter is covered in the schema.

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

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

Schema description coverage is 100%, so the conditional requirements ('bundle_id required for app_store', 'package_name required for play_store') and the type enum are already documented in the schema. The description largely restates that mapping rather than adding syntax, format, or edge-case meaning beyond it.

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 ('Creates an app in the project') and immediately enumerates the three app variants (test_store, app_store, play_store), which distinguishes it from sibling creators like create-product, create-offering, or create-entitlement without opening any 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?

Tells the agent which type to pick (test_store for simulated purchases with no store account) and gives a concrete next step ('call list-public-api-keys for the key the SDK uses'). It also sets a boundary by saying store credentials are added in the dashboard, not here. It stops short of explicit when-not-to-use guidance versus update-app.

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 this is a non-read-only, non-idempotent, non-destructive creation in a closed world, so the safety profile is covered. The description adds the runtime meaning of lookup_key (what the app checks), which is mild behavioral context, but omits whether duplicate lookup_keys are rejected, whether the call errors on an existing key, and what it returns.

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, zero filler, and the action is front-loaded. The second sentence is somewhat mis-placed for a description (it reads like parameter documentation) but earns its place by showing the runtime access pattern.

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

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

For a three-parameter creation tool with no output schema and no annotations gaps, the description is adequate but thin: it never says what a successful call returns or yields (e.g. an entitlement id for later attach-products-to-entitlement calls), nor how it behaves when the lookup_key already exists.

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

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

Schema description coverage is 100%, including examples for lookup_key, display_name, and the project_id fallback rule, so the baseline is 3. The description reinforces lookup_key with a concrete access pattern (customerInfo.entitlements["pro"]) but adds no syntax or constraint information the schema lacks.

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 ("Creates an entitlement"), which cleanly distinguishes it from create-product, create-offering, and grant-customer-entitlement. It stops short of clarifying how it relates to sibling list-entitlements or attach-products-to-entitlement, but the core action 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as grant-customer-entitlement (which provisions for a customer rather than defining the entitlement itself). The example of lookup_key usage is helpful but is parameter guidance, not usage 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 declare it is a non-read-only, non-destructive, non-idempotent open-world write. The description adds real behavioral context beyond that: the project's first offering is automatically promoted to current unless is_current is used. No auth or error/failure behavior is 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?

Two tight sentences, front-loaded with purpose and followed by the one behavioral rule an agent must know. Nothing is wasted or repeated from the structured fields.

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 5-param create tool with no output schema and adequate annotations, the description covers purpose and the key side effect. It is slightly thin on failure modes (duplicate lookup_key) and project_id resolution, but nothing critical to calling it 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 meaning the schema lacks: the interaction between omitting is_current and the automatic current-offering promotion. The remaining parameters (project_id resolution, metadata) 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+resource and even defines the domain concept ('a set of packages the paywall shows'), which helps separate it from the nearby create-packages sibling. It is clear but does not explicitly contrast itself with any alternative tool.

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 one conditional guidance clause ('set is_current to make this one current'), but never says when to prefer this over create-packages or what prerequisites/ordering exist. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation/safety profile is covered. The description adds the post-creation workflow step but says nothing about auth scope, duplicate lookup_key behavior, or failure modes beyond what annotations provide.

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

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

Two sentences, zero filler, with the core action front-loaded and the follow-up workflow trailing. Nothing in it is redundant with the schema or 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 5-param mutation tool with no output schema, the description covers the action, the key conventions, and the next step. It omits what happens on conflicts (duplicate lookup_key) and any response detail, but is otherwise sufficient to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by enumerating the canonical lookup key values ($rc_monthly, $rc_annual, etc.), which the schema only hints at with "e.g. $rc_monthly" — genuinely additive semantic content.

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 — "Creates a package in an offering" — which is concrete and distinguishable from sibling create-offering. It doesn't explicitly contrast itself with other create-* siblings, but the offering-scoped framing makes the target obvious.

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 actionable workflow guidance: use RevenueCat standard lookup keys where they fit, then follow up with attach-products-to-package. It names the downstream sibling and the sequencing, though it doesn't state when-not to use this tool (e.g., vs. reusing an existing package).

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 the safety profile (readOnlyHint false, destructiveHint false, non-idempotent), so the description needn't repeat that. But the description adds no behavioral context beyond annotations: no error cases (duplicate store_identifier), no permission requirements, no side effects of creating subscriptions.

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 efficient sentences with the core purpose and a key parameter constraint front-loaded. No waste, though neither sentence addresses the broader context of when to use this tool.

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

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

For a 6-parameter creation tool with no output schema, the description is thin: it omits prerequisites, error behavior, and the relationship to siblings like create-entitlement or verify-store-credentials. Should do more.

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 six parameters. The description reinforces store_identifier semantics and subscription_duration usage but does not add format or constraint details beyond the schema. 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+resource: creates a product. The differentiation from siblings like create-app or create-entitlement is implied by the resource name, but there is no explicit routing to alternatives such as update-product or list-products. Adequate but not maximally distinguishing.

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?

Implies usage through setup context (store_identifier, subscription_duration) but provides no explicit when-to-use or when-not-to-use guidance, and no mention of prerequisites like verifying store credentials. Minimal viable guidance.

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

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

Annotations declare the safety profile (non-read-only, open-world, non-idempotent), and the description adds real behavioral context beyond them: it runs through the same pipeline as a real purchase (events, transactions, webhooks) but is sandbox-only. It still omits whether the simulation is reversible or what side effects persist, keeping it from a 5.

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

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

Two sentences, front-loaded with the core action and scope, followed by the critical constraint (never touches Apple or Google) and the use case. 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 5-parameter mutation-style tool with no output schema, the description covers what it does, the sandbox boundary, and the intended verification use. It does not describe the return payload or whether simulation state persists, a minor omission against rich schema coverage and annotations.

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

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

Schema description coverage is 100%, so the enum scenario values, offset_days bounds, and product_id formats are already fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Simulates a purchase lifecycle in the project's Test Store') for one app user, and immediately distinguishes itself from real purchases by noting it never touches Apple or Google. An agent can tell this apart from refund-subscription or extend-subscription without opening 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?

Explicitly names the intended use case ('check that entitlements and webhooks work'), which gives clear context for selection. It does not name alternatives or exclusions (e.g. when to prefer a real store's flow), so it stops short of a 5.

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

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

Beyond the annotations (which only declare write/non-idempotent/non-destructive), the description discloses two critical behavioral facts: the signing secret is returned exactly once and cannot be retrieved again, and the custom Authorization header is configured in the dashboard rather than via this call. These are non-obvious and directly actionable.

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 with zero filler, front-loaded with the core action and followed by the two most consequential operational caveats. Every sentence earns its place.

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

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

With no output schema present, the description compensates by describing the one significant return value (the one-time signing secret). Combined with the dashboard note and clear event scope, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, establishing a baseline of 3. The description reinforces the event-type concept but adds no syntax or format detail beyond the schema, and its uppercase event names even differ from the schema's documented lower-case values.

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 ('Adds a webhook') and immediately scopes what it does by naming the event payloads it receives (INITIAL_PURCHASE, RENEWAL, etc.). An agent can distinguish this create operation from the sibling list-webhook-integrations and delete-webhook-integration 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 explains what the webhook is but never states when to use this tool versus alternatives, nor any preconditions (e.g. project/app required, entitlement to create webhooks). No sibling is named as an alternative and no exclusion is given, so usage must be inferred from the purpose 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 declare destructiveHint=true, readOnlyHint=false, etc., so the description's job is to add context beyond safety flags. It adds crucial behavioral details: deletion is permanent, includes their data, store subscriptions are not cancelled, and requires user confirmation. However, it doesn't mention potential irreversibility warnings or what happens to related resources beyond subscriptions (e.g., entitlements). Still, it's informative beyond annotations.

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

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

The description is a concise single sentence (plus a short follow-up) that front-loads the permanent deletion and scope, then adds key caveats and a call to action. Every part earns its place 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?

Given the destructive nature and lack of output schema, the description provides essential context: permanence, data deletion, non-cancellation of store subscriptions, and confirmation requirement. It covers what an agent needs to invoke correctly and responsibly. It could be more complete by specifying what other related data is affected (e.g., entitlements) or any rate limits, but it's largely 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 100%, so parameter semantics are fully documented in the schema. The description adds meaning by instructing to 'ask the user to confirm the app user id first', which clarifies the required customer_id parameter (app user id). However, it doesn't add new semantic details beyond the schema's own descriptions. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description states a specific verb (deletes) and resource (customer and their data), and clarifies the scope 'permanently' and 'from this project'. It distinguishes from siblings like cancel-subscription or revoke-customer-entitlement by its permanent data-deletion nature, though it doesn't explicitly name alternatives. This is clear but lacks explicit sibling differentiation.

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

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

The description provides clear context: it's for a data-deletion request, store subscriptions are not cancelled, and asks to confirm the app user id. It gives a specific instruction to confirm before deleting, which guides usage. However, it doesn't explicitly state when to use this vs. other deletion-like tools (e.g., revoke-customer-entitlement), so it's not a full 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing two consequences: delivery history is destroyed along with the integration, and events stop being sent to the URL. It does not mention irreversibility or error behavior on repeat calls.

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

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

Two short sentences, zero filler, and the destructive scope is front-loaded. 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?

For a two-parameter destructive tool with no output schema and annotations covering the safety hints, the description covers purpose, data loss, and runtime effect. Minor gap: no statement about reversibility or what a successful call returns, though annotations partially compensate.

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 (project_id, webhook_id) are already documented in the schema. The description adds no syntax, format, or optionality detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Deletes) and resource (webhook integration) plus scope (its delivery history). Clearly separable from the sibling list-webhook-integrations, create-webhook-integration, and delete-customer operations without opening any 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 verb rather than stated: no guidance on when to delete vs. disable, no prerequisites, and no mention of the alternatives (e.g., deleting an app or archiving). An agent can infer the purpose, but nothing routes it here versus another tool.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds real operational constraints not in the annotations: platform scope (Google Play and App Store) and the App Store rule that a reason is required with a 90-day maximum. It stops short of describing failure behavior or whether an extension can be reverted.

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 action and intent, followed by platform caveats. No filler, and the most decision-relevant constraint (App Store 90-day cap and reason requirement) is placed where an agent will see it.

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 non-idempotent mutation with no output schema, the description covers intent, platform scope, the App Store precondition, and where to obtain the subscription id. It leaves open edge cases such as extending an already-expired subscription, but nothing critical 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 description coverage is 100%, so the schema already documents every parameter, including the mutual exclusivity of extend_until/extend_by_days and the Apple reason requirement. The description's 'by days, or until a date' largely restates 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 precise verb and resource ('Adds time to a subscriber's existing subscription') and immediately scopes the intent ('for support or goodwill'). An agent can distinguish this from siblings like cancel-subscription, refund-subscription, and grant-customer-entitlement without opening any 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?

Gives a clear use context (support or goodwill extensions) and platform conditions, plus a concrete sourcing instruction ('Take the subscription id from get-customer'). It does not explicitly state when not to use it versus refund-subscription or grant-customer-entitlement, which would be needed for a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so safety is covered. The description adds genuine value beyond them by disclosing that credential entries reveal only whether they are configured (no secrets returned), which tells the agent what sensitivity to expect from the response.

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 front-loads the resource and lists only returned fields; every clause carries information. It is a fragment rather than a sentence, but nothing is wasted.

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

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

With no output schema, the description bears the return-value burden and largely meets it by enumerating the notification URLs, last-notification/processed status, last forward, purchase flag, and credential-configured flags. Minor gaps remain (no explicit statement that this is a read of current settings), but it is sufficient 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 app_id and project_id are already documented, and the description does not restate or add meaning to them. Baseline 3 applies; the App Store Connect / Google Play Pub/Sub note clarifies a returned field, not a parameter.

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

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

The description names the resource (an app's store notification setup) and enumerates the specific fields returned, so an agent knows exactly what it retrieves. It stops short of an explicit verb ('Get'/'Retrieve') and never distinguishes itself from siblings, but the resource is unmistakable.

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 call this versus alternatives, and no prerequisites or context (e.g., to configure or verify store notifications). The usage is only implied by the field list.

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 readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the safety bar is met. The description adds genuine domain context beyond that: it enumerates the returned data and explains the semantics of gives_access ("whether each one grants access now"), which an agent cannot get from annotations. It stops short of describing not-found behavior or error cases.

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 sentence, front-loaded with the action and key, then the returned payload. No filler and every clause carries information.

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

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

With no output schema, the description correctly shoulders the burden of describing return values and does so with four enumerated categories plus an interpretation hint for gives_access. Remaining gaps such as error/not-found behavior or whether results are cached are minor for a read-only lookup.

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 are already documented in the schema, dictating a baseline of 3. The description restates the customer_id key ("app user id") but says nothing about project_id, so it adds no 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 specific verb+resource ("Looks up a customer") and specifies the key (app user id) plus the payload returned: entitlements, attributes, subscriptions, one-time purchases. The singular lookup is clearly distinct from the sibling list-customers in spirit, but no sibling is named to make the boundary explicit.

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?

"Looks up a customer by app user id" implies the lookup key but gives no when-to-use guidance, no prerequisites, and no alternatives (e.g. list-customers for discovery vs. this for a known id). An agent must infer the selection 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds what is reported (including the pending-Google-Play-token signal), but it does not discuss scoping, refresh behavior, or result shape beyond the counts.

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 tight sentence with no filler, front-loading the triggering context before the data it returns. It is slightly dense and couches a tool purpose inside a CLI reference.

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 does name the counts returned, which is enough for an agent to know what to expect from this read-only status 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%, and the single optional project_id is fully documented in the schema, including the 'optional when the key or account has exactly one project' rule. The description adds nothing about the parameter, 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 names the resource and the specific data returned — customer/subscription counts and Google Play subscriptions pending a purchase token. It is distinguishable from every sibling, though the phrasing is anchored to a CLI invocation rather than stating the verb+resource directly.

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 signals the triggering context: use this after running `npx revenuedot import` from RevenueCat. No alternative tool is named, but there is no sibling that overlaps this import-status role, so the guidance 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations, namely that omitting `metric` returns a fixed overview card set while supplying it returns daily history over `days` days.

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 tightly written sentences with no filler. The two-mode structure is front-loaded and immediately usable by an agent deciding whether to pass `metric`.

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 rich annotations, complete schema descriptions, and no output schema, the description adequately explains what both return modes look like. It does not discuss project/environment scoping or error cases, but those are handled by the schema and 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 goes beyond the schema by explaining the interaction between `metric` and the returned data shape, making the conditional parameter behavior clearer than the per-parameter schema text alone.

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 what the tool returns in two distinct modes: an overview card set when `metric` is omitted, and a daily history for the named metric when it is provided. The resource (revenue metrics) and the branch condition are unambiguous, though the action verb is implied rather than stated.

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 explains the internal conditional usage of the `metric` parameter ('Without metric... With metric...'), but gives no guidance on when to invoke this tool versus other sibling tools such as get-project-health or list-transactions. Usage is implied for anyone already looking for revenue metrics, but there is no explicit context or exclusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it aggregates multiple diagnostics (credentials, notifications, webhooks) across every app in one call, which is exactly the value an agent needs to know. No rate-limit or cost details, hence not a 5.

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

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

Two short sentences, front-loading what the tool checks and then when to reach for it. Every clause earns its place and there is 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 read-only aggregate diagnostic with complete annotations and no output schema, the description adequately conveys scope and intent. It does not hint at the result shape (per-app pass/fail structure) or whether checks are ordered, which is a minor residual 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?

There is a single optional parameter with 100% schema description coverage, so the schema already carries the semantics (project_id format, optionality when the account has one project). The description adds no additional parameter meaning, which is the expected baseline when schema coverage is high.

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

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

The description names a specific resource (setup health) and enumerates exactly what it inspects: per-app store credential validity, notification arrival, and webhook delivery. This clearly differentiates it from single-purpose siblings like verify-store-credentials and list-webhook-deliveries by positioning it as an aggregate diagnostic.

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 it first when something looks wrong" gives an explicit triage entry point, which is actionable guidance. It stops short of naming the alternative checks to run after this one, so it is clear context without full when/when-not 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 already declare non-read-only, non-destructive and idempotent, yet the description adds real behavioral detail beyond them: access auto-expires, it is revocable via a named sibling, the customer is auto-created if new, and a repeat grant with the same end date is a no-op.

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

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

Three short sentences, front-loaded with the core action, then consequences, then idempotency. Every sentence carries information an agent needs; none is 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 a fully described schema and annotations covering the safety/idempotency profile and no output schema to explain, the description supplies everything else an agent needs: side effects, reversibility, and repeat-call behavior.

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 four parameters including the accepted expires_at formats. The description only restates expires_at's role as the expiry boundary and adds the auto-creation side effect, which is behavioral rather than parameter-level detail.

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

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

States a specific verb (grants) plus resource (time-limited entitlement access) and scope (until expires_at). It also names the sibling that reverses it, revoke-customer-entitlement, so an agent can distinguish the pair without opening either 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?

Gives a clear use context ('for support or goodwill') and points to the alternative verb for undoing the grant. It stops short of stating when not to use it (e.g., versus a purchased subscription flow), so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the useful result-granularity fact (one app per store, ids only), but says nothing about pagination behavior or how next_page is surfaced despite limit/starting_after being present.

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 zero waste; the identity/scope statement is front-loaded and the downstream dependency (needs an app id) is secondary. Nothing 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 read-only list tool with full schema coverage and annotations, the description supplies what the schema can't: the per-store granularity and the fact that ids are the payload. It is slightly thin on pagination flow, but no output schema exists so nothing crucial is missing.

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

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

Schema description coverage is 100%, so limit, project_id and starting_after are all documented in the schema (including the cursor's origin in next_page). The description adds no parameter-level meaning beyond aligning with "the project's apps"; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (lists) and resource (the project's apps), and adds scope detail that distinguishes it (one per store: app_store, play_store, test_store, stripe). An agent can tell it apart from list-products, list-projects and the create-* siblings without opening any 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?

"Product creation needs an app id" gives clear context for why an agent would call this and links it to the create-product flow, which is real usage guidance. It stops short of explicit when-not conditions or naming a direct alternative, so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint. The description adds a scoping constraint (exact match) for search, which is useful context. It does not mention pagination behavior or return format, but annotations cover the safety profile.

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

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

A single, front-loaded sentence conveying default sort, search keys, and the recommended follow-up action. No 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?

Given read-only annotations and full parameter schema, the description is nearly complete for a list tool. It omits only cursor-based pagination details (though starting_after is in schema). No output schema, but return shape is inferable for a list of customers.

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 parameters (limit, search, project_id, starting_after) are documented in the schema. The description only adds that search is 'exact match' and 'app user id, the $email attribute, or a store transaction id,' which slightly overlaps with schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

States a specific verb (list/search) and resource (customers), and details the search keys (app user id, $email attribute, store transaction id). Distinguishes from sibling get-customer by specifying search-by-identifier semantics and routing to get-customer for retrieval.

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 says when to use: 'find who a support request is about, then call get-customer.' Names the alternative (get-customer) and the condition that selects it. Also identifies default ordering (newest first).

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds useful output-shaping context by indicating each entitlement is returned with its unlocking products, but says nothing about pagination behavior or how many records come back.

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 compact sentence with the resource and the value-add output detail front-loaded, and no filler. 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 usefully sketches the return shape (entitlements plus unlocking products). Pagination exists in the schema but is not summarized in the description; since the schema already describes the cursor and limit semantics, this is a minor omission rather than a blocking 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 limit, project_id, and starting_after are fully documented in the schema itself. The description contributes no additional parameter meaning, which is the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb (Lists) and resource (the project's entitlements) and adds domain meaning by explaining what an entitlement is ('access levels such as pro') and what the result pairs with each ('the products that unlock each one'). It is distinguishable from create-entitlement/attach-products-to-entitlement, though it doesn't explicitly name a sibling.

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

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

There is no when-to-use guidance, no mention of alternatives, and no note about the optional project_id resolution behavior. Usage is only implied by the verb 'Lists'; an agent gets no routing or prerequisite context.

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

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

Annotations already carry the safe-read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavior: results are ordered newest first and the records are the same events delivered by webhooks, which implies payload shape and immutability beyond what the annotations say.

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 resource and ordering, then the use case, in a tight two-clause structure. The parenthetical list of five event types is informative but slightly heavy for a single sentence, keeping it just under maximum efficiency.

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 the return-shape burden; it mitigates this by defining events as webhook-identical and stating newest-first ordering. Pagination behavior is only inferable from the schema's starting_after cursor, leaving a small gap for a 6-parameter list 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 limit, types, project_id, customer_id, environment and starting_after are already fully documented. The description names three of the six filters (customer, type, environment) but adds no format or syntax detail beyond the schema; 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 resource (the event log), its ordering (newest first), and anchors it semantically by equating it with the events webhooks send, which cleanly separates it from the sibling list-webhook-deliveries. Concrete event type examples (INITIAL_PURCHASE, RENEWAL, CANCELLATION) make the resource 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?

Gives a clear scenario — 'filter by customer, type or environment to see why a customer lost access' — which tells the agent when this tool is the right lookup. It stops short of naming an alternative tool or stating a when-not condition, so it is context without exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds genuine domain context — that is_current is what the SDK shows by default — but says nothing about pagination behavior or result ordering.

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

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

Two sentences, zero filler, and the core purpose is front-loaded before the is_current note. 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?

For a read-only, zero-required-parameter list tool with rich annotations and full schema documentation, the description covers purpose and return structure adequately. Only minor gaps (pagination semantics, default result ordering) remain, and those are largely inferable from the schema.

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

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

Schema description coverage is 100%, so all three parameters (limit, project_id, starting_after) are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb (Lists) and resource (the project's offerings) and even discloses the return shape (offerings -> packages -> products). It doesn't explicitly differentiate itself from siblings like list-products or create-offering, but the hierarchy it describes is distinctive enough that an agent can identify it.

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

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

No when-to-use guidance, no prerequisites, and no routing to alternatives such as list-products for a flat product view. The is_current remark hints at default behavior but not at when to call this tool.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds the useful scoping detail that products are store product ids keyed per app, but says nothing about pagination behavior or result ordering beyond what the schema carries.

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 well-formed sentence with the core action front-loaded and the optional filter trailing. Nothing is redundant or padded.

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

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

For a read-only list tool with full schema coverage and annotations covering safety, the description is nearly sufficient. Only pagination and default page size expectations are unaddressed in prose, and those live in the schema descriptions.

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, app_id, project_id and starting_after are all documented in the schema itself. The description's app-scoping phrase merely restates what app_id's schema description already says, adding no syntax or format information.

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 ('Lists') and resource ('the project's products'), and clarifies what a product is ('store product ids per app'). It is clearly distinguishable from write siblings like create-product, though it never names a sibling tool directly.

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?

'Optionally for one app' hints at the app_id filter but gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as list-apps or list-entitlements. An agent must infer usage from context alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a real behavioral trait beyond them: the visibility of results depends on whether the caller is a secret key or an OAuth connection.

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 the core action front-loaded and the auth-scoping nuance second; zero 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 two-param list tool with full schema coverage and annotations covering the safety profile, the description is nearly complete. Only pagination behavior is unaddressed, a minor gap since the schema already documents the cursor.

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 both pagination parameters (limit, starting_after) are documented in the schema. The description adds no parameter syntax or format 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 ('Lists') and resource ('RevenueDot projects') plus the privilege scope of what is returned. No sibling competes for listing projects, so an agent can select this unambiguously.

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?

Explains the credential-dependent result set (secret key vs OAuth), which implicitly tells the agent what it will get, but gives no explicit when-to-use/when-not guidance or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds domain context (the key is public and ships inside the app, so it cannot change anything), which partly restates destructiveHint=false rather than adding new behavior beyond 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?

One front-loaded sentence that leads with the action and resource, with prefixes and safety context packed into trailing clauses. The final clause ('it is not a secret key and cannot change anything') is slightly redundant with the annotations, keeping it short of a 5.

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

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

For a two-parameter read tool with no output schema, the description supplies the value format (key prefixes) and the key's role, which is enough to call it correctly. Minor gap: the tool name is plural ('keys') while the description describes a single key, leaving the return cardinality slightly ambiguous.

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 app_id and project_id are already documented in the schema ('The app (see list-apps)', 'proj...'). The description adds nothing about parameter meaning or the optionality of project_id, 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 ('Lists an app's public SDK key') and goes further by enumerating the key prefixes (appl_, goog_, test_) and tying it to the RevenueCat SDK configuration. It also distinguishes the resource from a secret key, so an agent can tell it apart from credential-oriented siblings 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?

Usage is implied by the object it operates on (an app's public SDK key), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many list-* siblings. The clarification that it is not a secret key steers intent somewhat, but no routing condition is stated.

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, idempotent, non-destructive, closed-world), so the description only needs to add context — and it does: it discloses which event types appear in the ledger, that ordering is newest-first, and that price/USD revenue are attached. It stops short of noting sign conventions for refunds or pagination behavior.

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, front-loaded with what the tool returns and how it is ordered, then the optional scoping. No filler or redundancy.

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 100% schema coverage and safety annotations, the definition is largely self-sufficient for a read-only list tool. The main gap is that no output schema exists and the description doesn't mention the cursor/page shape (next_page/starting_after) an agent needs to page through results.

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

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

Schema description coverage is 100%, so limit, project_id, customer_id, environment and starting_after are already documented in the schema. The description adds only a light framing that customer/environment filters are optional single-value scopes, which is baseline-level value.

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

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

Names the concrete record set (purchases, renewals, trial starts, refunds) plus sort order and returned fields, which is far more specific than the name alone and distinguishes it from list-events or get-metrics. It never explicitly contrasts itself with a sibling, but the resource definition 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?

"Optionally one customer's or one environment's" implies the scoping use case (single-customer or single-environment revenue review) but is not phrased as guidance. No when-to-use vs. alternatives (list-events, get-metrics, list-customers) and no exclusions are stated.

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 establish readOnly=true, destructive=false, idempotent=true and openWorld=false, so the safety profile is covered. The description adds useful behavior beyond that: newest-first ordering and the fields returned (status, attempts, HTTP status, last error). It doesn't disclose pagination behavior, though schema covers 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?

Two tightly written sentences with no waste. Scope, ordering, and returned data are front-loaded, and the status-filter hint follows naturally.

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

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

For a read-only list tool with rich annotations and full schema coverage, the description is nearly complete. With no output schema, listing the returned fields is a valuable addition. It omits any note about pagination or cursor usage, though the schema handles 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 description coverage is 100%, so the baseline is 3. The description reinforces the 'status' filter and implies scope via 'one webhook', but adds no syntax or format details beyond what the schema already documents.

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 ('Delivery attempts for one webhook') plus ordering and returned fields, clearly distinguishing it from sibling list-webhook-integrations and retry-webhook-delivery. It doesn't explicitly name a sibling, but the scope 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?

It hints at usage with 'Filter by status to find failures,' but gives no explicit when-to-use guidance, prerequisites, or alternatives to consider (e.g., retry-webhook-delivery, list-webhook-integrations). Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the useful detail of what each integration records (URL, environment, event filters), which partially substitutes for the absent output schema, but says nothing about pagination, ordering, or auth requirements despite cursor parameters.

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 with no filler; the resource and its payload fields come first and nothing is redundant.

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 100% schema coverage, the description plus annotations give an agent enough to invoke it correctly, and the field enumeration compensates for the missing output schema. Only pagination behavior and result ordering are left unstated, 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 limit, project_id, and starting_after are fully documented in the schema itself (including the 1-100 range and cursor semantics). The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Lists) and resource (project's webhook integrations), and the parenthetical enumerates the returned fields (URL, environment, event filters), which cleanly separates it from list-webhook-deliveries. It stops short of explicitly naming that sibling as the contrast point, so it is clear but not fully differentiated.

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

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

No guidance on when to call this versus alternatives. With siblings like list-webhook-deliveries, create-webhook-integration, update/delete-webhook-integration, and send-test-webhook in the same family, the agent gets no signal about selection criteria or preconditions.

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 destructive/idempotent/non-readOnly, but the description adds materially new behavior: access ends immediately, refunds are limited to server-refundable stores, unsupported stores return an error explaining so, and money actually moves. That is exactly the context an agent cannot get from 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 short sentences, the side effect and store constraint are front-loaded, and every clause carries information (what happens, where it works, what to confirm first). 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 destructive, single-purpose mutation with no output schema, the description covers the action, its immediate consequence, store-specific availability, error behavior, and the confirmation precondition. Nothing essential to 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 description coverage is 100%, so subscription_id and project_id are already documented in the schema. The description adds no format or sourcing detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource plus the exact scope: 'Refunds the latest charge and ends access immediately.' This distinguishes it from cancel-subscription and extend-subscription without the agent needing to open any 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?

Gives an explicit precondition ('only call it after the user said yes to this exact customer and amount') and a store-availability condition (Google Play works, others error). It does not explicitly route to a named alternative for unsupported stores, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that it targets failed or pending deliveries and acts 'now', but does not explain side effects, whether the retry creates a new delivery record, or any rate/permission constraints.

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 a single, front-loaded sentence with no redundant or filler content. Every word contributes to conveying the action and the target delivery state.

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 retry operation, the combination of a fully documented schema and rich annotations covers most needs. The description adds the important eligibility condition ('failed or pending'), though it could say more about the expected outcome since no output schema exists.

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

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

Schema description coverage is 100%, so all three parameters are fully documented in the input schema, including project_id optionality and where to get delivery_id. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb ('Sends ... again') and resource ('a failed or pending webhook delivery'), making the retry action clear. It does not explicitly differentiate itself from siblings like send-test-webhook or list-webhook-deliveries, but the purpose 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 phrase 'failed or pending' implies the eligibility condition for using this tool, giving some usage context. However, it does not state when not to use it, nor does it point to alternatives such as list-webhook-deliveries for obtaining a delivery_id or send-test-webhook for test deliveries.

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, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value beyond them by scoping the destruction: only granted promotional access is removed and store purchases are unaffected. It does not mention auth requirements or what happens on repeat calls, but the destructive boundary is stated.

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 tightly written sentence: the core action and its sibling origin come first, the scope exclusion (store purchases) closes it. Every clause carries information and nothing is repeated from the schema.

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

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

For a small 3-parameter mutation with no output schema and full schema coverage, the description supplies the action, the counter-tool, and the blast radius. Permission requirements and post-revocation state are unspecified, but nothing essential to 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 description coverage is 100% and all three parameters (project_id, customer_id, entitlement_id) are documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or lookup-key nuance beyond what the schema already states.

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 (ends) and resource (promotional access granted to a customer), and explicitly names the sibling that creates it (grant-customer-entitlement) plus the alternative origin (dashboard). It also carves out what it does NOT touch (store purchases), so an agent can distinguish it from cancel-subscription or refund-subscription 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 clearly routes usage by naming the counterpart operation grant-customer-entitlement and defining the scope of what this revokes (promotional/granted access only, not store purchases). It does not spell out prerequisites such as required permissions or whether a grant must currently exist, so it stops short of explicit when/when-not guidance.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds genuinely useful context beyond them: the event is a TEST event, not a real customer-facing delivery, and the integration must be enabled. It doesn't say whether the test is logged as a delivery, but the key behavioral trait is 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?

Two short sentences with zero filler, leading with what the tool does and following with the one usage constraint. 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?

No output schema exists, but this is a simple action tool and the annotations carry the safety profile; the description covers purpose, precondition, and the test-only nature. Only minor gaps remain, such as what the caller receives or how the test appears in delivery history.

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 project_id's optionality/format and webhook_id are already documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, 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 (sends) and resource (a TEST event to a webhook integration) plus the intent ('so the user can see it arrive'). It is distinguishable from siblings like retry-webhook-delivery and create-webhook-integration, though it doesn't name an alternative 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?

Gives a clear precondition ('The webhook must be enabled') and the intent (letting the user see an event arrive) implies the when-to-use case is verifying an integration works. No explicit exclusions or named alternatives, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the null-means-delete rule, but that same rule is already in the schema's attributes description, and it does not explain overwrite vs merge behavior or permission requirements.

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

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

Two short sentences, front-loaded with the core action; the null-deletion caveat is sensibly placed second. Minor redundancy with the schema's own attribute description keeps it from a 5.

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 mutation tool with three params and no output schema, the description omits key context: whether existing attributes not listed are preserved, what a successful call returns, and per-call limits. Annotations cover safety, but the operational picture is only partially 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 the baseline is 3. The mention of $email/$displayName reserved keys adds a little meaning not spelled out in the schema, but the maxItems=50 limit and the project_id fallback rule 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 specific verb and resource ('Sets attributes on a customer') and clarifies that it can address either reserved keys ($email, $displayName) or custom keys. It is clearly distinguishable from read-side siblings like get-customer and list-customers, though it never explicitly names 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?

There is no when-to-use guidance: nothing says when to prefer this over get-customer, when attributes must already exist, or what prerequisites (project_id scoping) apply. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly=false, idempotent=true, and destructive=false, so the safety profile is covered. The description adds some value with the forwarding use case ("e.g. to RevenueCat during a migration") and the credentials boundary, but much of the per-field behavior it repeats is already in 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?

One dense sentence that front-loads the primary change (name) before the conditional store fields. Slightly awkward with stacked parentheticals, but nothing is wasted.

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

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

For a mutation tool with no output schema, the description covers mutable scope, the App Store/Google Play restriction, and the credentials exclusion, which is enough for correct invocation. A named alternative for credential changes would complete it.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the empty-string/null semantics. The description reinforces this but adds only the migration use-case color, which is the baseline expectation when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ("Changes an app's name") and enumerates the mutable fields, so an agent can immediately tell it apart from create-app and list-apps. It is clear but does not explicitly name a sibling for routing.

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 field list, and there is one useful boundary ("Store credentials are not changed here: the user enters them in the dashboard"), but no explicit when-to-use/when-not framing or 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 declare readOnly, idempotent, non-destructive and open-world. The description adds genuinely new behavioral context beyond that: it performs a live call to the store, and it deliberately never accepts or returns a key because credentials are entered in the dashboard. It does not cover rate limits or failure modes.

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

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

Two short sentences with zero padding; the core action is front-loaded and the security constraint follows naturally.

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

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

For a two-parameter, read-only verification tool with no output schema, the description covers what it does and roughly what it returns ('says whether they work'). Only minor gaps remain, such as the shape of the result or behavior when credentials are 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 app_id and project_id are already documented in the schema, including the 'see list-apps' pointer. 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: it checks already-saved Apple/Google store credentials for an app and reports whether they work. It also implicitly distinguishes itself from credential-creation tools by noting it never accepts or returns a key.

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 use case (validate stored credentials against the store) is implied clearly enough to invoke, but the description names no alternatives and no when-not conditions, e.g. when to prefer this over reading app store settings.

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