polar-sh

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

Annotations only provide destructiveHint=true, so the description carries most of the load and does so well: it discloses that cancellation is deferred to period end and that the customer retains access until then. It omits whether the action is reversible/undoable and any permission or idempotency requirements, which keeps it short of 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?

Three short sentences with zero filler; the critical behavioral fact (end-of-period, access retained) is front-loaded and the API mapping is relegated to the tail.

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 only a destructiveHint annotation and no output schema, the description covers the essential non-obvious behavior (deferred cancellation, retained access). It leaves out reversibility and auth expectations, so it is complete but not exhaustive.

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

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

Schema description coverage is 100%, so all three parameters (including the two cancellation-reason fields) are already documented in the schema. The description adds no parameter-level meaning, 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 (cancel) and resource (subscription) plus the timing scope ('at the end of its current period'). It is clearly distinguishable from the get/list subscription siblings, though it never names an alternative to contrast against.

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 purpose (call this when you want to cancel), and the end-of-period detail clarifies intent, but there is no explicit when-to-use/when-not guidance or comparison to sibling tools such as polar_get_subscription or polar_list_subscriptions.

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 supply destructiveHint=true, but the description never explains or acknowledges that hint, nor does it describe auth requirements, rate limits, or whether the created link is idempotent. It adds only the notion of 'reusability' and the underlying endpoint, which is modest value beyond the 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?

Two tight sentences with the core purpose front-loaded and no filler. The trailing 'Polar: POST /v1/checkout-links/' endpoint reference is marginally useful for an agent and adds minor noise.

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 five-parameter, fully schema-documented creation tool with no output schema, the description covers the essential purpose and that it yields a reusable URL. It omits any note on the mutation's side effects or the exact response shape, which slightly limits completeness.

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 in the schema. The description adds only the 'one or more products' implication, which the array type and schema description already convey; 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 ('Create a reusable checkout URL for one or more products') and clarifies scope including array-valued products. No sibling creates checkout links, so the agent can immediately distinguish it from the list/get tools around 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?

The phrase 'the link you put in a page or an email' gives implied usage context, but there is no explicit when-to-use vs when-not-to-use guidance, no prerequisites (e.g. product ids must exist), and no named alternative to route away from.

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, so the agent knows this mutates state. The description does add genuinely useful context beyond that ('moves real money back to the customer'), flagging real financial consequence. However, it omits whether the refund is reversible, what authorization is required, and any rate/limit constraints, so it only partially enriches the annotated 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?

Two short, front-loaded sentences with zero filler; the core action and its partial-refund scope come first, and the risk warning follows. Nothing wastes the agent's budget.

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?

All five parameters are documented in the schema and the destructive nature is covered, so the definition is nearly sufficient. The remaining gap is behavioral: nothing about irreversibility or the consequences of revoke_benefits, which matters for a money-moving tool with no output 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 five parameters are already documented, including the amount-omission behavior and the revoke_benefits default. The description's 'in full or in part' merely restates what the schema already says for amount, adding no syntax or edge-case 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 and resource ('Refund an order') and adds scope ('in full or in part'), which cleanly separates it from the read-only sibling polar_list_refunds. It never names a sibling explicitly, so it stops short of the top band, 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 description gives no when-to-use or when-not-to-use guidance and names no alternative tool. The closest thing to guidance is the caution that it moves real money, which warns about severity rather than helping the agent choose this tool over others.

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 adds the useful upstream mapping (GET /v1/customers/{id}) and confirms single-record scope. It discloses nothing further about pagination, error behavior, or authentication, so it adds modest value on top of 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?

Two short, front-loaded sentences with no filler; the verb and lookup key come first. The trailing 'Polar: GET /v1/customers/{id}' is largely restated by the schema path, keeping it just short of maximal 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?

For a one-parameter read tool whose annotations cover the safety profile, this is essentially complete. The only missing element is any hint about the returned customer payload, which matters slightly more given there is no output 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% with a single well-documented customer_id, so the schema carries the parameter burden. The description's 'by Polar id' and the path template add only marginal confirmation, which is the expected baseline.

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

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

States a specific verb (fetch) and resource (a single customer) keyed by Polar id, which cleanly separates it from the list-family sibling polar_list_customers. It does not distinguish itself from polar_get_customer_state or polar_get_customer_state_by_external_id, so an agent must infer that from the 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?

The description only implies usage via 'by Polar id'; it gives no explicit when-to-use, no prerequisite (e.g. you must already hold a Polar customer id), and names no alternative such as the state or external-id lookups. Guidance 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?

The readOnlyHint annotation already confirms this is a safe read. The description adds meaningful behavioral context by disclosing that it aggregates multiple resource types (subscriptions, benefit grants, entitlements) in a single call, which helps the agent understand the tool's composite nature. It still does not detail output format or pagination, but the added aggregation info is substantive.

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

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

The description is three short, front-loaded sentences that each earn their place: what it fetches, when it is the best answer, and the backing endpoint. There is no wasted language.

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 no output schema, the description gives adequate return-content hints and the endpoint. However, it omits guidance on when to prefer this over polar_get_customer or the by-external-id variant, which is important for selection among several customer-related siblings.

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 single customer_id parameter is fully documented in the schema. The description adds no additional meaning, format, or constraints beyond what the schema already provides, which is the expected baseline for high schema coverage.

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 has a specific verb ('Fetch') and resource ('everything about one customer'), and it enumerates the included data (active subscriptions, granted benefits, entitlements). It distinguishes the tool by scope ('full state') but does not explicitly name the sibling polar_get_customer, which would make it fully 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 gives an implied usage context in the form of a question ('The best answer to "what does this customer currently have?"'), which is helpful. However, it does not state when not to use this tool or explicitly compare it with sibling alternatives like polar_get_customer or polar_get_customer_state_by_external_id.

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

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

readOnlyHint=true already declares the safe-read profile, and the description reinforces it with the underlying GET endpoint. It adds the lookup-key semantic, which is useful, but no additional behavioral detail (not-found behavior, auth scope) 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 contrasting the two lookup paths, followed by the raw endpoint as a trailing anchor. No filler, and the distinguishing clause comes first.

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 with full schema coverage and a readOnlyHint annotation, everything an agent needs is present: purpose, distinguishing condition, parameter meaning, and the underlying API route. No output schema exists, so return-value documentation is not required here.

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 only one parameter exists, so the baseline is high. The description still adds real meaning by clarifying external_id means the caller's own id rather than Polar's internal id, disambiguating a plausible confusion.

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 ('get a customer's state') and explicitly frames the scope difference from the sibling polar_get_customer_state — lookup is by the caller's external id, not Polar's. An agent can pick between 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?

Names the alternative (polar_get_customer_state) and gives the selection condition: 'the usual path when you hold your own user id.' Clear context for when to use it, though it doesn't state a negative case (e.g., when you only have a Polar id, use the other).

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 only that quantities are aggregated per window, but says nothing about window-size limits, sampling, pagination, or auth scopes — gaps that matter for a metrics-style 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 tight sentences with the outcome front-loaded and the endpoint reference trailing. The 'Polar: GET /v1/meters/{id}/quantities' fragment is somewhat redundant but conventional and does not bloat the definition.

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 must carry the return shape, and it only says 'aggregated quantities' — it does not indicate that results are bucketed by the interval parameter or what fields each bucket contains. Adequate to call the tool, incomplete to interpret the response.

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 meter_id, start/end_timestamp, interval, and customer_id are all documented in the schema. The description adds no syntax, format, or default detail beyond that, 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 gives a specific verb ('Fetch the aggregated quantities') and resource ('a meter'), and adds the business framing that these quantities drive usage-based billing. It is distinguishable from siblings like polar_list_meters or polar_get_metrics, though it never explicitly names the alternative it is not.

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

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

Usage is only implied: the billing-charge framing suggests when this result matters, and the tool name/required params make the scenario obvious. There is no explicit when-to-use vs polar_get_metrics or polar_list_meters, and no stated prerequisites or 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?

readOnlyHint=true already establishes a safe read, so the description is free to add value elsewhere — and it does, by naming the four metric families returned and the GET /v1/metrics/ endpoint. It stops short of mentioning rate limits, max date spans, or pagination behavior for large series.

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

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

A single front-loaded sentence that carries the verb, resource, scoping, bucketing, metric list, and endpoint with no filler. Nothing to trim and nothing 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?

With no output schema, the description usefully serves as the only statement of what comes back (orders, revenue, MRR, active subscriptions), and it covers the date/interval framing. It is nearly complete for a read-only analytics tool; only edge behavior like span limits or empty-window handling is absent.

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 and organization_id are all documented in the schema itself. The description only restates the date-range/bucket concept at a high level, adding no syntax or constraint detail beyond the schema — the baseline 3.

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 (revenue and subscription metrics) and enumerates what the metrics are: orders, revenue, MRR, active subscriptions. That is enough for an agent to know this is the aggregate-analytics tool rather than one of the many polar_list_* siblings, though it never explicitly names or contrasts with 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?

The date-range and interval-bucketing framing implies the analytics use case, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as polar_get_meter_quantities or the list tools. Usage is inferable but not guided.

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. The description adds useful content about what the payload includes (line items, discount, tax), but says nothing about auth requirements, error behavior for a missing/invalid id, or scoping (is the order scoped to the caller's org?).

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 is fetched; the trailing 'Polar: GET /v1/orders/{id}' is redundant metadata but cheap and aids API mapping. 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?

There is no output schema, so the description carries the return-value burden, and it does list the main components (line items, discount, tax). Missing: any note on error handling for unknown ids and whether the full order object (status, totals, billing) is returned.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents order_id. The description adds no format or provenance detail (e.g. whether this is the Polar order id such as 'ord_...') 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?

Specific verb (fetch) plus resource (a single order) and an enumeration of what the order payload contains (line items, discount, tax). The word 'single' implicitly contrasts with the sibling polar_list_orders, though it never names that sibling 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: call this when you have one order_id and need that order, rather than listing orders. There is no explicit when-to-use/when-not-to-use statement and no named alternative (e.g. polar_list_orders) for the bulk case.

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, non-mutating read. Beyond that, the description usefully discloses that the payload includes prices and attached benefits (inline expansions an agent would otherwise not predict). It does not mention rate limits or not-found behavior, so the addition is modest.

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 padding, with the core purpose front-loaded ahead of the endpoint reference. Every element 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?

A simple one-parameter read-only tool with full schema coverage and annotations covering its safety profile. The only real gap is that no output schema exists, and the description partially compensates by naming the included prices and benefits, but does not describe the overall response shape.

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 required product_id, so the schema already documents the parameter. The description adds only the REST path mapping (GET /v1/products/{id}), which mildly reinforces that the id is a path parameter but adds no semantic 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?

Clear specific verb+resource: 'Fetch a single product'. It also adds the enrichment scope (prices and attached benefits), which tells the agent this is not a bare record fetch. It does not name the sibling it contrasts with (polar_list_products), so differentiation is implicit in the word 'single' rather than 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?

No when-to-use guidance and no alternatives named. An agent must infer that this is for fetching one known product by id versus using polar_list_products to enumerate. No prerequisites or error conditions are mentioned.

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 useful context about what the payload contains (product, price, period) and the underlying REST endpoint, but says nothing about error behavior for nonexistent ids or whether related resources can be expanded. Modest added value beyond the 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?

Two tight sentences with the resource and returned fields front-loaded, followed by the endpoint mapping. The endpoint reference is somewhat redundant with the title and name but is compact and 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 one-parameter read tool with no output schema and full readOnly annotations, the description is sufficient: it names what is fetched and what the payload includes. It lacks any note on error cases or expansion options, keeping it just short of fully 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 coverage is 100% for the single subscription_id parameter, so the schema already carries the semantics. The description only echoes the path variable via 'Polar: GET /v1/subscriptions/{id}' without adding format or sourcing guidance, 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 (Fetch) and resource (a single subscription) and clarifies the singular scope, which implicitly contrasts with the sibling polar_list_subscriptions. It never names that sibling explicitly, so differentiation relies on inference rather than a direct callout.

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 intent of retrieving one subscription by id is implied by 'single subscription' plus the {id} path, but there is no explicit statement of when to use this versus polar_list_subscriptions or what happens on a missing id. Usage is inferable but not 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?

readOnlyHint=true already establishes this is a safe read operation, lowering the disclosure bar. The description usefully adds behavioral context about the returned data ('whether the grant is still active'), which goes beyond the annotation. However, it says nothing about pagination behavior or result shape despite having no output schema, so it adds only moderate value.

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 zero waste, front-loading the core action and purpose. The endpoint mapping is a useful trailing detail that does not detract from the front-loaded purpose.

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 burden of explaining return values, and it partially does so by noting grant recipients and active status. It omits pagination behavior and the overall response structure, leaving gaps for a list tool. Adequate but incomplete given no output 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 page, limit, and benefit_id are already fully documented in the schema. The description adds no extra meaning about parameter syntax, ranges, or defaults beyond what the schema provides. Baseline 3 is appropriate 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 gives a specific verb and resource ('List who has been granted one benefit') and clarifies scope with 'of one benefit,' implicitly distinguishing it from the sibling polar_list_benefits. It clearly conveys this returns grant records rather than the benefits themselves. It stops short of explicitly naming a sibling alternative, so it lands at 4 rather than 5.

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

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

There is no explicit when-to-use guidance and no mention of the alternative polar_list_benefits for enumerating benefits. The reader can infer the tool requires a benefit_id, but there is no statement of prerequisites or when this should be preferred over other list endpoints. This is minimal implied usage only.

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, non-mutating read, so the description's job is easier. It adds little beyond that: no mention of pagination behaviour, result ordering, or that results are scoped/filtered by the optional organization_id. The endpoint string confirms the read-only nature but is largely redundant with 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?

One tight sentence that front-loads the action and immediately disambiguates the jargon term 'benefit', followed by the endpoint reference. No wasted words.

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

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

For a read-only list tool with no output schema and fully documented parameters, the description is nearly sufficient. The main omission is pagination/return-shape context, though page and limit are self-explanatory 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 all five parameters (page, limit, type, query, organization_id) are already documented in the schema. The description adds nothing about filtering semantics or how type/query interact, 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 goes further by defining what a benefit is ('the things a product grants, such as licence keys, file downloads or Discord roles'), plus the underlying endpoint. It does not, however, distinguish itself from the nearby sibling polar_list_benefit_grants, which 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?

Usage is only implied: an agent can infer it should call this when it wants the catalogue of benefit definitions. There is no statement of when to prefer this tool over alternatives, and no mention of the grants-vs-definitions distinction against polar_list_benefit_grants.

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 need not re-declare safety. It adds the backing endpoint (GET /v1/customers/), but says nothing about pagination behavior, result limits, or scoping caveats 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?

Two short sentences, front-loaded with the core action and filtering capability. The trailing endpoint reference is minor and slightly redundant but not wasteful; nothing else bloats the definition.

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 a fully documented schema and no output schema, the definition is adequate but thin. It omits any mention of the returned collection shape or that organization_id may be needed for multi-org tokens, leaving those to 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 five parameters (page, limit, email, query, organization_id) are fully documented in the schema. The description restates only email and query, adding no format or syntax 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?

States a specific verb ('List') and resource ('customers') and notes optional filtering by email or text query, which clearly separates it from polar_get_customer. It does not explicitly name siblings, but the list-vs-get distinction 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?

The phrase 'optionally by email or a text query' hints at when the filters are useful, implying a browse/search use case. However, it never states when to choose this over polar_get_customer or the customer_state tools, nor any exclusions, leaving guidance implied rather than explicit.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description adds almost nothing behavioral. It does not mention pagination, default page size, result ordering, or what happens when the token spans multiple organisations — the most operationally relevant fact for this 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, front-loaded with the purpose. The trailing 'Polar: GET /v1/discounts/' is largely redundant with the tool name and endpoint knowledge, but it is minimal waste.

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

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

For a read-only list tool with full schema coverage and no output schema, the description is minimally adequate but omits pagination semantics and multi-org scoping, both of which matter for correct invocation. Nothing is misleading, but real gaps 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?

Schema description coverage is 100%, so all four parameters (page, limit, query, organization_id) are already documented in the schema. The description mentions redemption limits but adds no format or syntax detail beyond what the schema provides. 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') plus what the records contain ('their redemption limits'). The tool is unambiguous relative to siblings like polar_list_benefits or polar_list_products, though it does not explicitly contrast itself with any of 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?

There is no guidance on when to call this versus alternatives, no prerequisites, and no mention that organization_id may be required for multi-org tokens (a condition the schema hints at but the description ignores). The agent must infer usage entirely.

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 these are raw ingested events for metering (useful distinction from aggregated/quantities data), but says nothing about pagination defaults, ordering, or volume/rate constraints for what could be a high-cardinality event stream.

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 front-loaded and no padding. The trailing 'Polar: GET /v1/events/' is endpoint metadata of marginal value to an agent, which keeps it out of 5 territory.

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 all 8 params fully described in the schema and a readOnlyHint annotation, the description covers enough to invoke it correctly. With no output schema, however, it gives no hint about the shape of an event record or pagination metadata, leaving a real gap for an agent interpreting 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 every one of the 8 parameters (name, page, limit, meter_id, customer_id, timestamps, organization_id) is already documented. The description's filter summary adds no syntax, format, or defaulting detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the raw usage events ingested for metering') and adds the filterable dimensions. It implicitly separates itself from polar_list_meters (meter definitions) by calling these 'raw usage events', but never names a sibling explicitly, 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 filter list ('customer, meter, name or time') implies when the tool is useful, and the read-only list framing makes intent clear, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool such as polar_get_meter_quantities or polar_list_meters.

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 only added behavioral fact is that keys carry a status. It does not mention pagination behavior, default page size, or the multi-organisation token caveat that the schema hints at.

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 purpose front-loaded and no wasted words. The trailing endpoint reference is mildly redundant but cheap and useful for API mapping.

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

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

For a simple read-only list tool with full schema coverage and readOnlyHint annotations, the essentials are covered, but with no output schema the description should say more about the shape of returned keys (e.g. pagination envelope, key objects). Adequate but with a clear 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%, with all five parameters (page, limit, status, benefit_id, organization_id) documented in the schema itself, so baseline 3 applies. The description adds no filter syntax or formatting detail beyond what the schema provides.

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 ('licence keys') plus the returned attribute ('their status'), and names the underlying endpoint. It is distinguishable from the many sibling list_* tools by resource, though it does not explicitly contrast itself with 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?

There is no guidance on when to use this tool versus alternatives (e.g. polar_list_benefit_grants, polar_get_customer_state) or when not to use it. The agent must infer usage purely 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?

The readOnlyHint annotation already makes clear this is a safe read operation. The description adds semantic context about what a meter represents, but it does not disclose pagination behavior, authentication scope, return shape, or other operational details 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?

Two sentences, front-loaded with the purpose, followed by a compact API endpoint reference. There is no wasted language and the structure is easy to scan.

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 fully described parameters and a readOnlyHint annotation, the description is mostly complete. It does not explain the returned meter fields, but no output schema exists and the core purpose is clear.

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 input schema. The description adds no parameter-level detail such as how page, limit, or organization_id behave, so the baseline of 3 is appropriate.

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

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

The description gives a clear verb and resource (list usage meters) and adds useful domain meaning: meters aggregate events into billable quantities. It does not explicitly distinguish this from the related sibling polar_get_meter_quantities, which is the main reason 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, when-not-to-use, or alternative guidance. The endpoint path is included, but it does not tell an agent whether to choose this over polar_get_meter_quantities or polar_list_events.

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 and there is no contradiction. The description adds essentially nothing behavioral beyond the annotations and schema – no default page size, pagination behavior, or ordering of results – so it lands at the baseline.

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 zero filler; the filtering capability is front-loaded before the endpoint reference. 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 simple read-only list tool with a fully documented schema and annotation-covered safety, the description is largely sufficient. It is slightly thin for a 9-parameter tool with no output schema: it never mentions pagination defaults or the shape of the returned list, though 'List orders' implies a collection.

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 every parameter documented in the schema itself, so the baseline is 3. The description's filter list mirrors the schema and adds no syntax, format, or default-value detail (e.g. date window semantics) beyond what is already structured.

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 orders') and enumerates the filter dimensions (customer, product, subscription, status, date window), which lets an agent distinguish it from the singular polar_get_order sibling. It does not explicitly name or contrast with any sibling tool, 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 description lists what can be filtered but gives no when-to-use context, no prerequisites, and no routing to alternatives such as polar_get_order for a single order. Usage is only implied by the verb '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?

readOnlyHint=true already covers the safety profile. The description does add one genuine behavioral fact beyond the annotations — results are limited to organisations the current token is authorized for — plus the upstream endpoint. It says nothing about pagination behavior or result shape, so the addition is modest.

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 the 'start here' directive, then the endpoint reference. 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 zero-required-parameter read-only list with no output schema, the description covers purpose, scope, and its role as the entry point for the toolset. Pagination semantics are left to the schema, which is acceptable since limit is capped at 100 there.

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 'page' and 'limit' fully documented in the schema itself. The description adds no 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) and adds a meaningful scope qualifier: 'the organisations the token can act for'. This distinguishes it from the many polar_list_* siblings that operate within a single organisation.

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' is explicit, actionable guidance that tells the agent to call this first to obtain the ID other tools require. It doesn't state a when-not condition or name a specific alternative, but the routing intent 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. Beyond that the description only appends the upstream REST endpoint (GET /v1/products/), which adds little behavioral context — no pagination semantics, no default page size, no ordering guarantees, and no indication of what the organization_id scoping implies for multi-org tokens.

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

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

One tight sentence front-loads the operation and its filters, followed by a short endpoint reference. Nothing is padded, though the trailing 'Polar: GET /v1/products/.' is arguably redundant with the name and carries minimal decision value.

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 a fully described schema and no output schema, most of what an agent needs is present. The description nevertheless omits pagination expectations and return shape, which is exactly the residual burden the description should carry when no output schema exists — enough to be viable, not enough to be 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 all six parameters (including page, limit, and organization_id) are already fully documented in the schema. The description mentions three of the filter parameters but adds no syntax, format, or interaction detail beyond what the schema provides, so baseline 3 applies.

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

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

The description states a clear verb (List) and resource (products), plus the specific filter dimensions (archived state, recurrence, text query), which distinguishes it from polar_get_product's single-item fetch. It stops short of naming any sibling explicitly, so full differentiation still requires reading the name or 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 'optionally filtered by...' — the agent can infer this is the collection-level browse/search tool versus polar_get_product for a known id. However there is no explicit when-to-use statement, no note that all filters are optional and that an unfiltered call returns everything, and no mention of 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?

The readOnlyHint annotation already establishes this is a safe, non-mutating read. The description adds the underlying REST endpoint (GET /v1/refunds/), which is mild extra context, but says nothing about pagination behavior, result ordering, or empty-result handling beyond what the schema's page/limit fields imply.

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 purpose front-loaded and no filler. The trailing 'Polar: GET /v1/refunds/' is marginal 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 lightly annotated list tool with a fully documented schema and no output schema, the description covers the essentials. It omits any hint of the response shape or pagination semantics, which an agent listing potentially large collections 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%, so every parameter is already documented in the schema, giving a baseline of 3. The description paraphrases filters but adds no format or syntax detail, and its mention of 'subscription' does not map to any actual 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 (List) and resource (refunds), plus the filter dimensions. However, it names 'subscription' as a filter dimension while no subscription parameter exists in the schema, which slightly muddies the scope. Still clearly distinguishable from siblings like polar_create_refund or polar_list_orders.

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 statement of when to use this versus alternatives (e.g. polar_create_refund for issuing a refund) and no prerequisites noted. Usage is only implied by the verb 'List' and the listed filters.

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, non-mutating read, so the bar is lower. The description adds the upstream endpoint mapping (GET /v1/subscriptions/), which is mildly useful for debugging, but says nothing about pagination defaults, result caps, or rate limits beyond what the schema implies.

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

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

Two sentences, no filler, with the capability statement front-loaded before the endpoint reference. 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 list tool with full schema coverage and a clear readOnlyHint annotation, the description covers purpose and filter scope adequately; return values need not be described since no output schema is expected. Minor gap: no guidance on combining filters or pagination 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 every one of the 8 parameters is already documented in the schema with its meaning. The description's filter list mirrors the schema rather than adding semantics such as accepted status values, id formats, or organization_id scoping rules. 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?

The description states a specific verb and resource ('List subscriptions') and enumerates the filter dimensions (customer, product, status, active state, cancellation window), so an agent knows exactly what the call returns. It does not explicitly distinguish itself from polar_get_subscription or the other polar_list_* tools, which is the only thing keeping it from 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 enumerated filters imply the usage context (bulk retrieval with narrowing criteria), but there is no explicit when-to-use guidance, no mention of the singular polar_get_subscription alternative, and no note on pagination strategy. Usage must be inferred rather than read.

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 burden is lower. It adds that results include HTTP outcomes, which is useful context, but says nothing about ordering, pagination limits, or retention windows. Adequate but not rich given the annotation coverage.

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

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

One tight sentence plus a routing endpoint notation; the diagnostic hook is front-loaded and nothing is redundant. 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 list tool with seven fully documented optional parameters and a readOnlyHint, the description is nearly sufficient, and 'with their HTTP results' gives a hint about return contents despite no output schema. It could still note that results are paginated for the agent to page through.

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

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

Schema description coverage is 100%, so all seven filters (succeeded, event_type, endpoint_id, timestamps, paging) are already documented in the schema itself. The description adds no filter semantics, 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 webhook delivery attempts') and adds the diagnostic framing 'why did my webhook not arrive?', which separates it in spirit from the sibling polar_list_webhook_endpoints. It stops short of explicitly naming the sibling it is not (endpoints vs. deliveries vs. redeliver), 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?

The quoted user question ('why did my webhook not arrive?') gives a concrete when-to-use context, which is more than most list tools provide. However, no alternatives or exclusions are named — e.g. it never points to polar_redeliver_webhook_event for retrying a failed delivery.

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 that each endpoint's subscribed events are returned, which is useful, but says nothing about pagination behaviour, ordering, or auth scope beyond what the schema implies.

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 what is listed. The trailing 'Polar: GET /v1/webhooks/endpoints.' is largely redundant with the tool name and could be dropped, but the overall size is small.

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

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

For a no-required-param, read-only list tool with full schema coverage and no output schema, the definition gives the resource and the return content, which is enough to call it correctly. Only pagination/ordering behaviour is left 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%, so page, limit, and organization_id are fully documented in the schema (including the multi-organisation caveat). The description adds no parameter-level meaning, which is the expected baseline here.

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 the configured webhook endpoints') and adds return scope ('and their subscribed events'). It is clear enough to distinguish from list_webhook_deliveries by resource name alone, though it never explicitly contrasts the two siblings.

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 listing intent is implied by the verb, but there is no explicit when-to-use, no mention of when to prefer polar_list_webhook_deliveries or polar_redeliver_webhook_event, and no prerequisites noted.

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, so the agent knows this is a state-changing action; the description reinforces the mutation ('queue ... for redelivery'). It adds no details on idempotency, whether the original delivery is replaced, retry behavior, or error handling if the event was already delivered — useful context that is absent.

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

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

Front-loaded with the action and its condition in one tight sentence. The trailing endpoint string 'Polar: POST /v1/webhooks/events/{id}/redeliver.' is mildly redundant with the tool name 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-parameter, no-output-schema action tool this covers what the agent needs to invoke it correctly. Minor gaps remain around return/error behavior, but nothing essential is missing.

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

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

Only one parameter (event_id) with 100% schema description coverage ('The webhook event to resend'), so the schema carries the semantics. The description adds no format or sourcing guidance beyond the schema, which is the expected baseline here.

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 (redeliver/queue) and resource (one webhook event), and the 'after your endpoint recovered' clause makes the intent unmistakable. It is clearly distinguishable from sibling read tools like polar_list_webhook_deliveries and polar_list_webhook_endpoints.

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 'after your endpoint recovered' gives a clear triggering condition for use. It does not, however, name an alternative or state when not to use it (e.g. vs. list_webhook_deliveries to inspect before retrying).

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