Polar MCP by usefulapi

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

Annotation only gives destructiveHint=true; the description adds the important nuance that cancellation is deferred rather than immediate and that the customer retains access until period end. It does not say whether the cancellation can be reversed or reverted, nor any auth/scope requirements, so it stops short of full behavioral disclosure.

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

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

Three tight sentences, front-loaded with the essential timing semantics before the endpoint reference. The 'Polar: PATCH /v1/subscriptions/{id}' fragment is marginally useful metadata rather than wasted space, but it is the one element not strictly needed by an agent.

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

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

For a low-complexity mutation with no output schema, the description covers what happens as a result (deferred cancellation, retained access). It leaves open reversibility and whether the reason/comment fields matter for the call, but nothing critical 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 all three parameters are already documented in the schema; the description adds no parameter-level meaning (e.g., that the reason/comment fields are optional and only used for churn reporting). Baseline 3 applies when the schema carries the load.

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 (cancel) plus resource (subscription) and immediately qualifies the timing semantics ('at the end of its current period'), which is the key differentiator from a hypothetical immediate cancel. An agent can read the first sentence and know exactly what this does.

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

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

The description implies when to use it (to cancel a subscription) and clarifies the deferred-effective behavior, but names no alternatives or conditions. No sibling tool competes for this action, so the risk of misrouting is low, but there is no 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 only supply destructiveHint=true, so the description does add real value by disclosing the "reusable" nature and the backing endpoint (POST /v1/checkout-links/). It still omits auth/permission requirements, whether a discount id is validated at creation time, and what happens on repeated calls with the same label. Adequate but not rich.

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 the core purpose front-loaded, followed by a short endpoint reference. The endpoint string is marginally useful but borders on trivia for an agent that only needs to pick and parameterize the 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?

No output schema exists, so the description would ideally hint at what a created link returns (URL plus id), which it does not. It covers creation adequately but leaves return shape and permissions unstated for a mutating 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 all five parameters (label, products, discount_id, success_url, allow_discount_codes) are already documented in the schema. The description only restates the cardinality of `products` ("one or more"), adding no format or constraint detail beyond the structured fields.

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 ("Create a reusable checkout URL"), scopes it to "one or more products", and clarifies intent with "the link you put in a page or an email". An agent can immediately distinguish this from the read-oriented siblings (list_products, get_order) 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 phrase "the link you put in a page or an email" implies the use case and the analog alternatives (checkout sessions via API), but it never states when to prefer this over another creation path or lists prerequisites such as needing product ids that already exist. Usage is implied, not instructed.

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

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

The destructiveHint annotation already flags this as a destructive operation, and the description earns credit by spelling out the concrete consequence: it moves real money back to the customer. That goes beyond the annotation's abstraction. It still omits whether the operation is reversible or idempotent, what auth/permissions are needed, and whether benefit revocation is permanent, so it is not full marks.

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

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

Two short sentences, front-loaded with the action and scope, then the risk warning, then the endpoint. 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?

For a destructive financial mutation with no output schema, the description covers the action, scope and monetary impact but says nothing about what is returned, whether a refund can be reversed or re-issued, or any idempotency behavior. Adequate against a fully documented schema and a destructiveHint annotation, but not complete for the operation's risk profile.

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

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

Schema description coverage is 100%, so amount, reason, comment, order_id and revoke_benefits are all documented in the schema itself, including the enum and defaults. The description's only parameter-relevant contribution is 'in full or in part', which duplicates the schema's 'Omit to refund the full order'. Baseline 3 is correct.

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

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

'Refund an order, in full or in part' gives a specific verb and resource plus a scope qualifier, and no sibling tool performs refunds, so it is easy to distinguish from the surrounding list/get/cancel tools. It stops short of naming an alternative or contrasting with, say, cancel_subscription, so it is clear but not sibling-differentiating.

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 reach for this tool versus alternatives (e.g., cancel_subscription, list_refunds) or any prerequisite such as having an existing order or the appropriate API scope. The only adjacent guidance is a warning about money moving, which is behavioral rather than 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 already declare readOnlyHint=true, and the description adds essentially nothing behavioral on top — no auth requirements, no failure modes for an unknown id, and no note on what data comes back. The API endpoint mapping is the only extra detail and it is not behaviorally informative.

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

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

Two short sentences, front-loaded with the action, no padding. The trailing 'Polar: GET /v1/customers/{id}' is mild filler but does anchor the tool to its upstream API.

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 single-parameter read tool this is close to adequate, but with no output schema the description could have said what a customer record contains or what happens for a missing id. It covers the call mechanics but stops short of being fully self-sufficient.

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

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

Schema description coverage is 100% and the single parameter is fully documented there. The description's 'by Polar id' merely restates the schema, adding no format, syntax, or id-provenance detail beyond it. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch a single customer by Polar id'), which is clearly distinct from the list counterpart polar_list_customers. It does not, however, distinguish itself from the similarly named siblings polar_get_customer_state or polar_get_customer_state_by_external_id.

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 'by Polar id' implicitly signals when to use this over the by-external-id variant, which is useful. But there is no explicit when-to-use guidance, no prerequisites, and no named alternative, leaving selection largely to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered structurally. The description adds real behavioral context beyond that: this is an aggregation call that returns subscriptions, benefits and entitlements in one shot, which matters for planning. It stops short of describing response shape, size or any rate limits.

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

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

Two short sentences plus an endpoint reference, with the payload contents front-loaded before the value proposition. Every clause carries information; nothing is padding.

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

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

For a one-parameter read tool with a readOnlyHint annotation, the essentials are present, and the description compensates for the missing output schema by naming what comes back. Minor gaps remain around pagination or response size, but an agent has enough 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?

There is a single parameter and schema description coverage is 100%, so the schema already states that customer_id is the Polar id. The description adds nothing about the parameter (e.g. id format or where to obtain it), so the baseline 3 for schema-documented params 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?

It uses a specific verb (Fetch) plus resource (customer) and enumerates what is returned: active subscriptions, granted benefits and entitlements. That is clearly distinguishable from list tools or polar_get_customer. It does not, however, differentiate itself from the sibling polar_get_customer_state_by_external_id, which is the one tool an agent could easily confuse it with.

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 best answer to what does this customer currently have?' implies a usage scenario, which is helpful framing. But there is no explicit when-not guidance and no routing to alternatives such as polar_get_customer (lighter lookup) or the by-external-id variant, so the agent must infer the choice.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST endpoint (GET /v1/customers/external/{external_id}/state), which is mildly useful, but says nothing about return payload, error cases (unknown external id), or caching/rate 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?

A single tight sentence leads with the differentiator, followed by the endpoint reference. Nothing is padded and nothing essential is buried.

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

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

For a one-param, read-only lookup with no output schema the description is nearly sufficient, and it defers to polar_get_customer_state for the semantics of 'state.' The one gap is that an agent that hasn't read the sibling tool won't know what 'state' actually returns.

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 the key semantic distinction that external_id is 'YOUR external id rather than Polar's' — clarifying what the value represents and where it comes from, which goes beyond the schema's terse 'Your own id for this customer.'

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 (get a customer's state) and explicitly differentiates itself from the sibling polar_get_customer_state by the lookup key. An agent can distinguish the two 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?

Provides real context for selection: 'the usual path when you hold your own user id,' which tells the agent when to prefer this over the Polar-id variant. No explicit negative guidance (e.g., when not to use it), but the alternative is clearly identified.

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

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

readOnlyHint=true already establishes this as a safe read, so the description's job is to add context beyond that. It does explain the windowed-aggregation semantics and the billing purpose, but says nothing about result size, pagination, or how many buckets are returned.

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 delivering purpose and business context, followed by a terse endpoint pointer. Efficient, though the API-path sentence adds little for an agent that already has the tool binding.

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 should hint at the return shape; 'aggregated quantities over a window' combined with the interval bucket-size parameter lets an agent infer a bucketed series, but the exact result structure and size limits are left unstated.

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

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

Schema description coverage is 100% with all five parameters documented, so the schema carries the parameter burden and baseline 3 applies. The description's phrase 'over a window' loosely reinforces start/end timestamps but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (Fetch) and resource (aggregated quantities a meter has recorded) and adds the business meaning ('what usage-based billing will charge for'), which cleanly separates it from polar_list_meters and polar_get_metrics. The endpoint reference confirms the exact resource being read.

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 billing framing implies when an agent would want this (usage aggregation over a window), but there is no explicit when-to-use/when-not guidance and no named alternative such as polar_get_metrics for cross-meter metrics. Usage is inferable 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is the bucketed-series semantics ('bucketed by interval') and the underlying endpoint mapping. It does not mention rate limits, whether metrics are pre-aggregated vs computed live, or latency, so it adds modest context beyond the annotation.

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

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

A single front-loaded sentence with no filler; the bucketing constraint and metric list come before the endpoint note. 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 partially compensates by naming the returned metrics and the bucket dimension, but it still leaves the series/response shape (e.g., per-bucket records, total vs. per-interval values) unexplained. It could say more about the return payload, but the metric enumeration covers the essentials.

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 start_date/end_date/interval/product_id/customer_id/organization_id are already documented in the schema. The description only restates the date-range and interval concepts without adding format or filter semantics beyond that baseline.

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

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

Specific verb (Fetch) + resource (revenue and subscription metrics) with the dimensions named (orders, revenue, MRR, active subscriptions) and the bucketing scope. It is clearly distinguishable from sibling list_* tools and the single get_meter_quantities 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 states the data shape but never says when to choose this over alternatives such as polar_list_orders/list_subscriptions for raw records or polar_get_meter_quantities for usage. No prerequisites, no exclusions, no routing 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?

readOnlyHint=true already declares this a safe read, and the description is consistent with that. It adds what the response contains (line items, discount, tax) but says nothing about 404/not-found behavior, auth requirements, or rate limits, which is acceptable given annotation coverage but not rich.

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 that leads with the purpose and tacks the REST endpoint on as a trailing reference. No filler; 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 read-by-id tool with no output schema, naming the returned components (line items, discount, tax) usefully compensates for the missing return schema. Only minor gaps in error/not-found behavior remain.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents order_id. The description adds no format, syntax, or sourcing detail beyond what the schema already states. 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?

Specific verb 'Fetch' plus resource 'a single order', with the payload scope spelled out (line items, discount, tax). 'Single' distinguishes it from the polar_list_orders sibling, so an agent can tell the two apart 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?

Usage is implied by the required order_id and the 'single order' framing, but the description neither names the alternative (polar_list_orders) nor states when to prefer this over it. No when-not or prerequisite 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=true, so the safe-read profile is covered. The description usefully adds that the response includes nested prices and attached benefits, which matters because no output schema exists. It stops short of noting 404/not-found behavior or auth requirements.

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

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

Two tight sentences, front-loaded with the essential action and return content. The trailing 'Polar: GET /v1/products/{id}' is mildly redundant with sentence one but harmless and occasionally useful.

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

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

For a one-parameter read-only getter with no output schema, the description covers the action, the identifier, and the shape of the returned payload. What is missing is error behavior and routing guidance relative to the list sibling.

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

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

Schema coverage is 100% with a single, self-documented product_id parameter, so the schema carries the load. The description adds no format, source, or example detail for the id beyond what the schema already says.

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

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

States a specific verb (Fetch) and resource (a single product) and even declares what comes back with it (prices, benefits). The singular 'a single product' implicitly distinguishes it from polar_list_products, but the sibling is never named, so differentiation is left slightly to inference.

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 or when-not guidance is given. It never tells the agent to prefer this over polar_list_products when the product_id is known, nor what to do if the id is unknown. Only the operation itself is described.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, lowering the burden on the description. The description adds which related entities are returned, which is useful, but says nothing about 404/not-found behavior, authentication scope, or expansion options.

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

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

Two compact sentences with no filler; the purpose and returned data are front-loaded, and the REST endpoint reference is a useful identifier kept at the end.

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

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

With no output schema, the description is the only signal about return shape, and it only names three fields. For a simple one-parameter read with safety annotations this is nearly adequate, but return details and error behavior remain unspecified.

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% for the single subscription_id parameter, so the schema already carries the semantics. The description adds nothing about id format or where the id typically comes from, so the 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 ('Fetch') and resource ('a single subscription') and adds the returned facets (product, price, period), which distinguishes it from polar_list_subscriptions. It does not name the sibling explicitly, but the singular framing makes the distinction inferable.

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 beyond the implication that the caller must already hold a subscription id. No alternatives (e.g. polar_list_subscriptions) or preconditions are named, so routing is left entirely to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the response indicates who received the grant and whether it is still active, which is useful return-context beyond the annotation, but it omits pagination or rate-limit 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: the purpose is front-loaded and the endpoint reference is secondary. Every word earns its place with no 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 no output schema, the description usefully summarizes the return content (grantee and active status). Pagination details are left to the schema, which thoroughly describes page and limit, so the description is nearly complete for this simple list operation.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description does not add syntax, format, or constraint details beyond what the schema provides, so baseline 3 is correct.

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

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

States a specific verb (List), resource (grants of a benefit), and scope (one benefit, active status). It distinguishes itself from the sibling polar_list_benefits by focusing on grants rather than benefits themselves.

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

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

Provides no explicit when-to-use guidance, prerequisites, or alternatives. The implied usage—listing grants for a known benefit—is evident but not stated, mirroring the MID calibration where a bare action description earned a 2.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lowered, but the description adds nothing behavioral beyond a definition: no word on pagination (page/limit), result ordering, or the fact that organization_id may be required for multi-org tokens. It discloses no traits the annotations do not already cover.

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 gives the verb, resource, domain meaning, and endpoint with zero filler. Nothing is restated or wasteful.

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 an annotated read-only list with full schema coverage and no output schema, the description covers purpose and domain vocabulary well. The only real gap is pagination/return behavior, which is a minor omission given the schema exposes page and limit.

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 page, limit, type, query and organization_id. The description adds no filtering or format semantics on top of 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 and resource (list benefits) and adds a concrete gloss of what a benefit is (licence keys, file downloads, Discord roles), which an agent can anchor on. It does not differentiate from the close sibling polar_list_benefit_grants or polar_list_products, so it falls short of a 5.

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

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

There is no when-to-use guidance, no exclusion, and no named alternative, even though polar_list_benefit_grants sits adjacent and is easily confused with this tool. The API endpoint reference (GET /v1/benefits/) is not usage 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?

readOnlyHint=true already establishes this as a safe read, so the description's burden is lower. It adds only the REST endpoint mapping and says nothing about pagination defaults, result ordering, or what happens when organization_id is omitted on a multi-org token.

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 front-loads the core action and filters. The trailing 'Polar: GET /v1/customers/.' endpoint mapping is slightly redundant for an agent but costs little.

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, no-required-param, read-only list tool with no output schema, the essentials are covered. However, the multi-org caveat on organization_id (documented only in the schema) and pagination behavior are not surfaced, leaving gaps an agent may hit at call time.

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

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

Schema coverage is 100% with each of the five parameters documented, so the baseline is 3. The description echoes email and query but adds no semantics for page, limit, or organization_id beyond what the schema already says.

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

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

States a specific verb+resource ('List customers') and its optional narrowing (email or text query), which is enough to distinguish it from the singular polar_get_customer sibling. It does not explicitly name that sibling, so differentiation is implicit 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?

The phrase 'optionally by email or a text query' implies when to use which filter, but there is no explicit guidance on when to prefer this list tool over polar_get_customer or polar_get_customer_state, nor any prerequisite (e.g. organization_id when the token spans orgs).

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

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

The readOnlyHint=true annotation already tells the agent this is a safe read, so the description's main added value is the underlying endpoint reference (GET /v1/discounts/) and the note that results carry redemption limits. It does not disclose pagination behavior, result ordering, or whether an empty result/absent organization_id changes scope.

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 operation and resource, with no filler. The trailing REST endpoint reference is marginal value for an MCP agent but costs almost nothing in length.

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 paginated list tool with no output schema, the description covers what the tool returns at a high level but omits return-shape and pagination semantics that the schema alone doesn't convey. With annotations covering the safety profile, this is adequate but not complete.

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

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

Schema description coverage is 100%, and all four parameters (page, limit, query, organization_id) are fully documented in the schema, including the multi-org caveat on organization_id. The description adds nothing 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 and resource ("List discount codes") and adds scope detail about redemption limits. The resource is unique among siblings, so no routing ambiguity, but the description does nothing to distinguish its behavior from the other list_* tools beyond naming the resource.

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

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

There is no explicit when-to-use guidance, no statement of prerequisites, and no mention of alternatives. Usage is only implied by the verb "List". An agent must infer that this is the tool for enumerating discount codes rather than, e.g., looking them up individually.

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, covering the safety profile. The description adds that these are raw ingested events for metering plus the underlying endpoint, which is modest extra context; it says nothing about pagination behavior or result volume beyond what the schema already documents for page/limit.

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 purpose front-loaded; the trailing endpoint reference (GET /v1/events/) is mildly redundant but harmless.

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 fully documented parameters and no output schema, the description conveys what the records are and how they can be narrowed. It is adequate, though it stops short of describing the shape of a returned event or pagination expectations.

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 8 parameters are already documented. The description's filter list duplicates the schema fields without adding syntax, format, or interaction details, 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 (List) and resource (raw usage events ingested for metering) and enumerates the filter dimensions. The word 'raw' implicitly distinguishes it from aggregate siblings like polar_get_meter_quantities, but no sibling is named explicitly.

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

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

Usage is implied by the filter list (customer, meter, name, time), so an agent can infer when this is appropriate, but there is no explicit when-to-use guidance and no exclusion pointing to the aggregation alternative (polar_get_meter_quantities) when summarized data is wanted.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only that status is returned alongside keys and cites the REST endpoint; it does not disclose pagination defaults, whether revoked/expired keys are included by default, or any rate/auth constraints. With annotations doing the heavy lifting, this is adequate but thin.

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 the resource and return content front-loaded before the endpoint reference. Nothing is bloated, though the bare endpoint citation adds little for most agents.

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?

A read-only list tool with fully documented parameters and clear annotations needs little prose, so this is close to sufficient. It still omits pagination behavior and result-set scope, which an agent calling a paginated list endpoint would benefit from knowing.

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 each of the five parameters is documented in the schema with its meaning and constraints. The description adds no additional parameter meaning (e.g. filter combination behavior), 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 ('List issued licence keys') plus the underlying endpoint, so the agent knows exactly what the tool does. It does not differentiate itself from the many other polar_list_* siblings (orders, products, subscriptions), but the resource 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 guidance on when to use this versus alternatives, no mention of prerequisites or that filters like status/benefit_id exist to narrow results. The agent must infer usage entirely from the name and schema.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds no behavioral context beyond that — nothing about pagination defaults, result size, or what a meter record contains. Including the HTTP route is orientation, not behavioral disclosure.

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

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

Two compact sentences with the core purpose front-loaded and no filler; the route reference is appended rather than padding the opening.

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 endpoint with no output schema, the description covers the essentials but leaves the return shape (meter fields, aggregation config) undefined and says nothing about how pagination behaves. Adequate, not complete.

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

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

Schema description coverage is 100% and all three parameters (page, limit, organization_id) are documented in the schema, including the multi-org caveat. The description adds no parameter detail, so baseline 3 applies.

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

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

The description states a specific verb+resource ('List the usage meters') and adds a clarifying gloss on what a meter is ('aggregate events into billable quantities'), plus the underlying REST route GET /v1/meters/. It does not explicitly distinguish itself from the sibling polar_get_meter_quantities, but list-vs-get is inferable from the verb.

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 such as polar_get_meter_quantities, nor any prerequisites or ordering guidance. The only usage signal is the implicit 'list all meters' framing.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds value by naming the underlying endpoint (GET /v1/orders/), but does not disclose pagination behavior (page/limit), default page size, or result ordering. With annotations carrying the safety profile, this is adequate but thin.

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 clauses, front-loaded with the action and resource, followed by the filter scope and endpoint. 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?

For a read-only, zero-required-parameter list tool with full schema coverage, the description covers purpose and filtering scope adequately. It omits pagination expectations (default limit, total counts) and result ordering, which would fully round it out, but nothing essential to invoke 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 all nine parameters are already annotated in the schema. The description restates the filter categories at a high level (customer, product, subscription, status, date window) without adding format or syntax 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 (List) and resource (orders) with the available filter dimensions enumerated. It is clearly distinguishable from the singular polar_get_order, but it does not explicitly name any sibling as the alternative path, so it stops short of full 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 filter list implies the intended use case (querying the order collection by customer/product/subscription/status/date), but there is no explicit when-to-use-vs-when-not guidance nor a pointer to polar_get_order for single-order retrieval. Usage is inferable 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=true, so safety is covered. The description adds genuinely useful context that results are scoped to the token's permissions, but says nothing about pagination behavior (page/limit exist) or result volume, which matters for a listing tool.

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

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

Two short sentences: purpose first, then the action-guiding hint, plus a compact endpoint reference. Nothing is redundant or 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 simple, annotation-covered, zero-required-param list tool with no output schema, the description covers purpose, placement in the workflow, and the underlying endpoint. It could note result shape or that pagination is available, but nothing critical is missing.

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

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

Schema coverage is 100%, with both page and limit fully documented in the schema (1-based page, size 1-100). The description adds no parameter meaning 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 (List) and resource (organisations) with a scoping qualifier ('the token can act for'), and clarifies its role as the root entry point relative to the many sibling list/get tools. An agent can immediately tell it apart from polar_list_customers, polar_list_products, etc.

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

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

'Start here — most other tools take an organization_id' gives clear sequencing guidance that no sibling provides. It lacks an explicit when-not clause, but the prerequisite relationship is stated concretely enough to route the agent correctly.

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

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

readOnlyHint=true already declares the safe read profile, so the bar is lower. The description adds the upstream REST mapping (GET /v1/products/) but says nothing about pagination behavior or result ordering, which would be useful for a paged list endpoint.

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 no padding and the primary action front-loaded. The trailing API mapping is marginally useful but slightly filler-like.

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?

A read-only list tool with a fully documented schema and no output schema; annotations cover the safety profile, so little is missing. Pagination semantics are the only notable omission and are partially covered by the page/limit 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% and all six parameters are documented there, so the description contributes only redundant filter names. 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 (List) and resource (products) and enumerates the filter axes (archived state, recurrence, text query). It does not explicitly contrast with the read-one sibling polar_get_product, so it falls short of a 5.

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

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

The mention of optional filters implies the browsing/listing use case, but there is no explicit when-to-use, when-not-to-use, or pointer to a single-item alternative like polar_get_product.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description only restates the HTTP endpoint (GET /v1/refunds/), adding no behavioral context such as pagination behavior, result ordering, or what happens when the token spans multiple organizations (the organization_id note lives only in the schema). Nothing contradicts the annotations, but nothing is added either.

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 clauses, front-loaded with the purpose before the endpoint reference. The trailing 'Polar: GET /v1/refunds/.' is mostly filler but costs little.

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 paginated list tool with full schema coverage and readOnlyHint annotations, the description is nearly sufficient. It omits any hint of the returned refund shape, which matters slightly more here because there is no output schema, but an agent can still invoke it 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 six parameters are already fully documented in the schema and the baseline is 3. The description adds no format or syntax detail beyond the schema, and its 'subscription' filter mention does not correspond to any 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?

States a specific verb and resource ('List refunds') plus the filter dimensions, so it is clearly distinguishable from the other polar_list_* siblings that cover different resources. Minor flaw: it advertises filtering by 'subscription', but no subscription parameter exists in 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?

No when-to-use guidance, no exclusions, and no routing to alternatives such as polar_create_refund or polar_get_order for the filter ids. The filter list implies how to narrow results but never says when this tool is the right choice versus the single-refund or order tools.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the filterable dimensions and the backing endpoint (GET /v1/subscriptions/), but says nothing about pagination behavior or result ordering beyond what annotations and schema carry.

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

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

Two compact sentences, front-loading the verb+resource and the filter dimensions, with the endpoint noted last. No filler, though the endpoint string is only marginally useful.

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 a readOnlyHint annotation, the description is essentially sufficient; the absence of return-format detail is fine since no output schema exists but the operation is a straightforward list. Only explicit pagination/ordering guidance 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 all 8 filters are already documented with their own descriptions (including the useful organization_id token-span note). The description merely restates a subset of those filters (customer, product, status, active, cancellation) and adds no syntax or format detail, 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 (List) and resource (subscriptions), and enumerates the filterable dimensions. It does not explicitly differentiate itself from the sibling polar_get_subscription (single-resource fetch), so routing depends on the agent's own inference.

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 or when-not guidance is provided; nothing tells the agent this is for browsing/filtering multiple subscriptions versus fetching one. The filter list is descriptive but not prescriptive about 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral value by stating that results include the HTTP outcome of each delivery attempt, which is what makes the debugging framing actionable. It omits operational details such as delivery retention window or pagination defaults, but it is well above the annotation-provided floor.

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

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

Two compact sentences with the purpose and the use-case hook front-loaded before the API mapping. The trailing 'Polar: GET /v1/webhooks/deliveries' is informational rather than functional, a minor use of space, but nothing is bloated.

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 endpoint with zero required parameters and no output schema, the description covers what the tool does and why an agent would call it. It could note that all parameters are optional filters or mention pagination behavior, but no critical calling information 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 seven filters (page, limit, succeeded, event_type, endpoint_id, start/end_timestamp) are documented in the schema itself. The description adds no filter semantics beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb+resource ('List webhook delivery attempts') and qualifies it with what is actually returned ('with their HTTP results'), which separates it from polar_list_webhook_endpoints (configuration) and polar_redeliver_webhook_event (action). It does not name a sibling explicitly, so it stops just short of a 5.

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

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

'the tool for "why did my webhook not arrive?"' gives a concrete diagnostic scenario that tells the agent when this list tool is the right pick over other list tools. No explicit when-not conditions or named alternatives are provided, so it is clear context rather than full routing 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=true, so the safety profile is covered. The description adds only that each endpoint carries its subscribed events; it says nothing about default page size, ordering, or result caps, so it is adequate but not rich.

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 purpose. The trailing 'Polar: GET /v1/webhooks/endpoints.' is largely redundant with the name and title but costs little.

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 three optional params and no output schema, the description is minimally sufficient but omits pagination behaviour and any indication of what a returned endpoint record contains.

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 page, limit and organization_id are fully documented in the schema itself. The description contributes no additional parameter meaning, which matches the baseline for schema-complete inputs.

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

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

States a specific verb and resource ('List the configured webhook endpoints') plus the payload detail ('their subscribed events'). It is distinguishable from the closest sibling polar_list_webhook_deliveries by resource, though it never names that sibling or explains the boundary.

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 the nearby alternatives polar_list_webhook_deliveries or polar_redeliver_webhook_event. An agent must infer the selection logic 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 declare destructiveHint=true, and the description aligns by framing redelivery as an action that queues a real event. Adding that the endpoint has recovered gives useful context about prerequisites. Minor gap: no mention of idempotency or duplicate-delivery risk, which matters for a redelivery action.

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 the action and the recovery condition. The API path suffix is boilerplate but harmless.

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 single-param mutation with no output schema and destructiveHint set, the description covers the trigger, the action, and the target adequately. The endpoint/path reference is slightly extraneous but not misleading.

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

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

Schema coverage is 100% and the single parameter event_id is fully documented. The description adds only that it is a webhook event to redeliver, matching the schema. Baseline 3 since 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?

Clear verb 'redeliver' plus specific resource 'webhook event', and disambiguates from sibling polar_list_webhook_deliveries by naming the action rather than a listing. An agent can tell exactly what this does 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?

States the condition for use: 'after your endpoint recovered', which implies the endpoint was previously failing. No explicit when-not-to-use or alternative named, but the recovery context is a clear trigger.

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