Dub MCP by usefulapi

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

The description adds real behavioral context beyond the destructiveHint annotation by explaining the outcome of approval (partner gains links and earns commission). However, it says nothing about reversibility, required permissions/auth, or rate limits, which matters for a state-changing operation.

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 action and its effect, with no wasted words. The trailing 'Dub: POST /partners/applications/approve' 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 simple 2-parameter mutation with no output schema, the description covers the what and the outcome. It is missing guidance on prerequisites and whether approval is reversible or triggers side effects like notifications, which the agent would need in lieu of richer annotations.

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

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

Schema description coverage is 100%, so both applicationId and groupId are already documented in the schema. The description adds no format, constraint, or default information beyond what the schema provides, so the baseline 3 applies.

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

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

Specific verb+resource ('Approve a partner application') and it states the consequence of the operation (partner gains links, starts earning commission). The unambiguous verb separates it from dub_reject_partner_application and dub_list_partner_applications, though it never names those siblings 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?

No when-to-use or when-not-to-use guidance is given. It does not tell the agent that this is the counter-operation to dub_reject_partner_application, nor does it mention preconditions (e.g. application must be pending).

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

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

The annotations already declare readOnlyHint=true, covering the safety profile. The description adds useful cost/performance context ('Cheaper than listing') and notes the grouping behavior, but it does not disclose rate limits, auth requirements, or the exact return structure. With annotations handling the safety baseline, this 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 tight sentences plus the API endpoint reference. The core purpose and the key differentiator (cheaper than listing) are front-loaded, and every sentence contributes value without repetition or filler.

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

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

Given a simple count tool with four well-documented parameters, no required fields, and readOnlyHint annotations, the description is nearly complete. The main gap is that it does not describe the return shape (e.g., total count vs. grouped breakdowns), which would help for the groupBy case, but with no output schema this is a minor omission.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters in detail. The description mentions grouping dimensions and filtering, which aligns with the schema but adds no new syntax, format, or edge-case information. 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 uses a specific verb ('Count') and resource ('links'), states the scope (matching a filter, optionally grouped by domain, tag or folder), and distinguishes itself from the list operation ('Cheaper than listing when you only need totals'). An agent can tell this apart from dub_list_links 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?

It gives clear context for when to use this tool ('when you only need totals') and contrasts it with the alternative ('listing'), but it does not explicitly name the sibling tool (dub_list_links) or state exclusions. The guidance is sufficient for an agent to choose 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?

With destructiveHint=true already declared, the description adds almost nothing: it does not mention required permissions, workspace scoping, whether the folder applies to existing links, or naming uniqueness constraints. The only extra fact is the underlying API mapping (POST /folders).

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 action and purpose front-loaded; nothing is wasted. The trailing 'Dub: POST /folders' is a minor API breadcrumb rather than essential 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?

There is no output schema, so the description should ideally say what a successful creation returns or how the new folder is identified. It is minimally adequate for a simple 3-parameter create tool but leaves behavioral gaps around permissions and effects.

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 three parameters documented, so the schema does the work. The description adds no semantics for 'accessLevel' (the enum parameter) or the optional description field, leaving the baseline score appropriate.

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

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

The description states a specific verb and resource ('Create a folder') plus the purpose ('grouping links'), which distinguishes it from sibling read tools like dub_list_folders. It does not differentiate from the other create tools (dub_create_link, dub_create_tag), but the resource noun carries the distinction.

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 create a folder versus using tags or link metadata, no prerequisites (e.g., workspace/plan requirements), and no mention of alternatives. The agent must infer usage entirely from the name.

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

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

Annotations already supply destructiveHint=true, and the description neither contradicts nor enriches that. It says nothing about permissions/scopes required, duplicate-key behavior, rate limits, or side effects, so for a 9-parameter mutation it adds almost no behavioral context.

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

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

Three short sentences with the core purpose front-loaded. The trailing 'Dub: POST /links' is marginally useful endpoint metadata but is essentially internal implementation detail that an agent does not need.

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 nine parameters, one required, and no output schema, the description is thin: it does not say whether the created link object is returned or what happens on a key collision. The rich schema compensates for parameter documentation, keeping this at a minimum-viable level rather than inadequate.

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

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

Schema description coverage is 100%, so the schema already documents all nine fields, establishing a baseline of 3. The description's note to omit `key` merely restates the schema's own 'Omit for a random one', adding no syntax, format, or constraint 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 (Create) and resource (short link), matching the title exactly. It is distinguishable from dub_update_link and dub_delete_link by the verb, but it never explicitly contrasts with sibling operations such as dub_get_link or dub_list_links.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no conditions. The only guidance is a parameter hint about omitting `key`, which is usage of a field rather than usage of the tool.

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

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

Annotations supply only destructiveHint=true, which the description neither confirms nor explains (an unusual flag for a creation tool that an agent would benefit from having clarified). No side effects, permission requirements, uniqueness constraints on tag names, or idempotency behavior are disclosed.

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

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

Two short sentences with the core purpose front-loaded and no filler. The trailing endpoint reference is mildly redundant but cheap and could aid 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 two-parameter create tool with no output schema, the description covers the minimum: what it does. It omits what the call returns (the created tag) and any constraints on tag names, which leaves modest gaps for a mutation 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 both parameters (name, color with its enum) are already fully documented in the schema, and the description adds nothing beyond that. Baseline 3 applies when the schema carries the parameter burden.

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 tag for organising links"), which is unambiguous on its own. However it does not distinguish itself from siblings like dub_list_tags or dub_create_folder, and the "Dub: POST /tags" fragment merely restates the operation as an endpoint.

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 create a tag versus listing or reusing an existing one, nor any mention of prerequisites or when this tool should be avoided. The agent is left to 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 only supply destructiveHint=true, so the description earns real credit by disclosing the immediate effect ('URL stops resolving immediately') and the collateral loss of analytics. It stops short of permissions requirements, recoverability, or error behavior on an already-deleted link.

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 compact clauses, consequence front-loaded before the API mapping, with zero filler. Every sentence 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 one-parameter destructive tool with no output schema, the description covers purpose, immediacy, and side effects. Nothing further is needed for an agent to 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 coverage is 100% and the single parameter's description ('The link to delete.') already covers it. The description adds no format or sourcing detail (e.g., whether linkId is the key or the slug), 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 ('Delete a short link') that cleanly separates it from the create/update/get link siblings, and the endpoint mapping (DELETE /links/{linkId}) reinforces the operation.

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

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

Deletion intent is implied and the irreversible consequence is stated, but the description never says when to use this versus dub_update_link or dub_list_links, nor any precondition (e.g., confirm the link exists first). Usage is inferable from the verb alone.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds real value by disclosing that results are aggregated and grouped by a dimension, and that click/lead/sale events are covered. It stays silent on pagination, rate limits, and response shape for a 10-parameter tool with no output schema.

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

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

Front-loaded and compact: the capability, then the grouping dimension, then positioning. The trailing 'Dub: GET /analytics.' is mildly useful API mapping but the least valuable sentence and borders on filler.

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

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

For a 10-param analytics endpoint with full schema coverage and no output schema, the description covers purpose, aggregation semantics, and grouping adequately. It would be stronger if it hinted at the response shape (totals vs timeseries) since no output schema exists to do that job.

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 10 well-described parameters, including documented enums for event and interval, so the baseline is 3. The description restates the event types and gives dimension examples that mirror the groupBy enum, adding no syntax or interaction 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 and resource ('Get aggregated click, lead and sale analytics') plus the grouping capability and the covered event types. 'The main reporting read' positions it as the primary analytics endpoint, though it does not explicitly name dub_get_partner_analytics as the sibling it differs from.

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 by the phrase 'The main reporting read' – an agent can infer this is the default reporting tool, but there is no explicit when-to-use, when-not-to-use, or comparison against dub_get_partner_analytics or dub_count_links. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that attribution is returned as part of the payload, useful context, but says nothing about not-found behavior, authentication, or error handling for an id-based lookup.

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

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

Two short sentences with zero padding; the purpose and the endpoint mapping are front-loaded and immediately actionable.

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

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

For a one-parameter read tool with no output schema, the description does enough: it names the resource and flags that attribution comes back. It could say more about the returned shape or missing-customer behavior, but nothing essential to correct invocation 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% and the single customer_id parameter is documented in the schema as the Dub id. The description only restates this via the GET /customers/{id} path, adding no format or sourcing detail beyond the schema. 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 (Fetch) and resource (a single customer) plus the notable detail that attribution is included, which distinguishes it from a mere lookup. It implies the retrieval of one record versus the sibling dub_list_customers, though it never names that sibling.

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

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

The singular framing ('a single customer') implies it is used when you already have a customer id, and the GET path reinforces that. However, there is no explicit when-to-use statement and no reference to dub_list_customers as the alternative for browsing customers, leaving routing to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds the upstream endpoint mapping (GET /links/info). It does not disclose failure behavior (missing link), auth requirements, or rate limits. With annotations covering the safety profile, this is acceptable 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 sentences, zero filler, with the primary action and lookup modes front-loaded and the API reference tacked on at the end where it belongs. 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?

The description is adequate for selection, but with no output schema present it should say something about what a successful fetch returns or what happens when the link is not found, and it should note that identifiers are mutually exclusive rather than optional-all-at-once. Minor 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by grouping the four fields into three mutually exclusive lookup patterns ('id', 'external id', or 'domain plus key'), clarifying that domain/key must be supplied together. It stops short of stating which combination takes precedence.

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) plus resource (a single short link) and enumerates the lookup modes, which cleanly separates it from dub_list_links and dub_count_links in the sibling set. The agent knows exactly what operation it is selecting 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?

The description explains how to identify the link (by id, external id, or domain plus key), which is usable invocation guidance, but it gives no explicit when-to-use versus alternatives, no prerequisites, and no note on what to do when no identifier matches. Usage is implied rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description needn't repeat that. It adds no behavioral context of its own — no pagination, aggregation limits, default time window, or rate-limit notes — and the trailing 'Dub: GET /partners/analytics' merely restates the endpoint already implied by the tool name.

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 metric list front-loaded; nothing is padded. The 'Dub: GET /partners/analytics' clause is mild redundancy against 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?

No output schema exists, so the description should ideally describe the shape of the response beyond naming metric categories; it partially does this but says nothing about time-range defaults, required pairing of start/end, or how grouping changes the result.

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

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

Schema description coverage is 100% and the interval enum is self-documenting, so the baseline is 3. The description's 'per partner' phrasing only loosely gestures at partnerId/groupBy and adds no syntax, defaults, or interaction rules (e.g. groupBy=timeseries vs top_partners) beyond the schema.

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

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

States a specific verb+resource ('Get analytics for the partner programme') and enumerates the metrics returned (clicks, leads, sales, revenue). An agent can see this scopes to partners rather than links, but the description never explicitly distinguishes it from the sibling dub_get_analytics.

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 exclusions. With 'dub_get_analytics' present as a sibling, the agent gets no rule for choosing between partner-scoped and general analytics; the choice must be inferred from the tool name alone.

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

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

The readOnlyHint annotation already establishes this is a safe read, and the description adds the concrete upstream endpoint 'GET /commissions', which reinforces that. However, it discloses nothing beyond that: no pagination defaults, no ordering, and no note on what an empty result means. Useful but thin against a low annotation bar.

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 the filter dimensions immediately after. Nothing is padding; the endpoint reference is a single short clause.

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

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

With 100% schema coverage and a read-only annotation, the input side is adequately covered. But with no output schema, the description should carry more of the return-value burden and says nothing about the response shape, pagination metadata, or result ordering, leaving a real gap for a 7-parameter list tool.

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

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

Schema description coverage is 100%, so every parameter (page, type, status, interval, pageSize, partnerId, customerId) is already documented in the schema, including the interval enum. The description restates the filterable dimensions generically and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: 'List partner commissions'. The filter dimensions (partner, status, customer, time window) sharpen the scope, and the resource is clearly distinct from siblings like dub_list_payouts and dub_list_partners, though it never names an alternative explicitly.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives in the sibling set (e.g. dub_list_payouts, dub_get_partner_analytics). Usage is only implied by the listed filter dimensions, leaving the agent to infer intent.

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 'GET /customers' merely restates that. It adds nothing about pagination behavior (page/pageSize), default page size, result caps, or auth requirements, which is the context a read-only listing tool would benefit from.

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 the resource first. The trailing 'Dub: GET /customers' adds little beyond the verb already stated and the tool name, but the total length is tight and non-repetitive.

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 could reasonably say what a listed customer contains or how pagination is returned, which it omits. It is minimally adequate for a filtered list endpoint whose safety profile is covered by annotations.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description's mention of email/external id/link loosely maps to three of them but contributes no format or syntax detail beyond the schema. 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 customers Dub has attributed to links') and enumerates the filter axes (email, external id, link). This distinguishes it from the singular sibling dub_get_customer, 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 by the filter axes listed, but the description never says when to prefer this over dub_get_customer (single lookup) or dub_list_events/commissions. No explicit when-to-use or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds workspace scoping and the GET endpoint mapping, but discloses nothing about result ordering, default page size, or pagination behavior beyond what 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, front-loaded with the resource scope, and the endpoint mapping is a compact addition. No filler or repetition.

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 documented parameters, the definition is nearly sufficient. The absence of an output schema is the only reason more could be said about return shape (e.g., whether results are paginated).

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, search, archived, and pageSize are fully documented in the schema. The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (short domains configured on the workspace), and the 'Dub: GET /domains' mapping pins down the underlying endpoint. It is clearly distinguishable from sibling list tools such as dub_list_links or dub_list_tags by resource, though it does not explicitly contrast 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?

Usage is implied by the unique resource (there is no sibling alternative for enumerating domains), but the description gives no explicit when-to-use, prerequisites, or filtering context despite exposing search/archived 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?

The readOnlyHint annotation already establishes this is a non-destructive read, so the description only needs to add context. It adds that results are row-level rather than aggregated, but says nothing about pagination behavior, result caps, or ordering — notable given page/limit parameters exist.

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 that front-load the core purpose followed by the disambiguating contrast. No filler, no restatement of the title, and the endpoint reference is compact.

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 8 all-optional filters, 100% schema coverage, and no output schema, the definition covers purpose adequately but leaves the shape of a returned event row and pagination semantics unexplained. For a list tool with no output schema, a sentence on the result payload would close the remaining gap.

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

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

Schema description coverage is 100%, so every parameter including event, interval, linkId, customerId, start/end, page and limit is already documented. The description adds no syntax, format, or interaction detail (e.g., interval vs start/end precedence) 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?

States a specific verb (list) and resource (individual click/lead/sale events) and explicitly differentiates itself from aggregate analytics, which distinguishes it from the sibling dub_get_analytics. The appended 'Dub: GET /events' endpoint reference anchors the operation precisely.

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 'rather than aggregates — the row-level detail behind the analytics' tells the agent when this tool is appropriate versus summary reporting, which is clear implicit routing. It never names the alternative tool (dub_get_analytics) or lists exclusions, so it stops short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description only adds that access levels are included in the result. It says nothing about pagination behavior despite page/pageSize parameters, result ordering, or result size 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, front-loaded with the purpose. The 'Dub: GET /folders.' clause is minor REST reference padding but not harmful.

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 documented parameters this is adequate, but with no output schema the description could have clarified the paginated response shape (which the page/pageSize params imply) to be truly 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 page, search, and pageSize are fully documented in the schema itself. The description adds no syntax or semantics beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb (List) and resource (link folders), and adds scope detail (their access levels). It is distinguishably about folders versus the many sibling list_* tools, though it doesn't explicitly contrast with dub_create_folder or other folder-related operations.

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 indication of when to use this versus alternatives, no prerequisites, no mention of what it complements (e.g., dub_create_folder). The only guidance is implicit in the resource noun.

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 tells the agent this is a non-mutating read. The description adds the endpoint hint 'Dub: GET /links.', which reinforces that profile, but says nothing about pagination behavior, default page size, result ordering, or rate limits beyond what the schema already exposes.

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 its filter dimensions. The trailing 'Dub: GET /links.' is mildly redundant but cheap and adds endpoint context, so it does not hurt much.

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, fully optional 7-parameter list tool with no output schema, the description covers all the filter axes an agent needs to choose between them. It omits only pagination defaults and result ordering, which are minor gaps given the rich 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 every one of the seven parameters is already documented in the schema with its own description. The description's filter list maps onto domain/tagNames/folderId/search but adds no format, matching, or combination semantics beyond the schema. 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 (short links) and enumerates the filter dimensions, so an agent knows exactly what the tool returns. It does not explicitly distinguish itself from the nearby dub_count_links or dub_get_link siblings, which keeps it short of a 5.

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

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

Usage is implied by the enumeration of filters (domain, tag, folder, search), which tells the agent this is the broad query tool rather than a single-record fetch. However, no when-to-use/when-not guidance or named alternative (e.g. use dub_count_links for totals, dub_get_link for one link) is given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful non-obvious scope constraint that results are limited to pending applications, but says nothing about pagination defaults, result ordering, or what happens when the page is out of range.

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 and the scoping qualifier before the API mapping. The 'Dub: GET /partners/applications' clause is mildly redundant but cheap and occasionally useful for API lookup.

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, zero-required-parameter read-only list this is close to adequate, but with no output schema the description could have sketched what an application record contains or that pagination metadata is not returned alongside, leaving the agent to infer the 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%, with page and pageSize fully described including bounds, so the baseline is 3. The description contributes no additional parameter meaning such as defaults or sensible values.

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

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

States a specific verb (list) and resource (partner applications) with a scoping qualifier (pending), which separates it from dub_list_partners. It does not explicitly name or contrast that sibling, but the resource noun is distinct enough that an agent can route correctly.

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

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

There is no when-to-use guidance, no mention that the sibling tools dub_approve_partner_application and dub_reject_partner_application operate on the records this tool returns, and no note that only pending (not approved/rejected) applications are surfaced as a filter. Usage is implied by the name and 'pending' qualifier 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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds nothing beyond that — no pagination behavior, default page size, or total-count semantics despite page/pageSize params. It also cites a 'country' filter that does not exist as a parameter, a minor inaccuracy against the schema.

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

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

Two short sentences, zero waste, with the resource and filter dimensions front-loaded before the endpoint mapping. Nothing is padded.

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

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

For a five-parameter, no-required-params listing tool with no output schema and only a readOnlyHint annotation, the description is thin: pagination defaults and the distinction from dub_list_partner_applications are left unexplained, though the core operation is adequately conveyed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description paraphrases the filter intent (status/email) but adds no semantics beyond the schema, and its mention of 'country' does not correspond 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?

Clear specific verb+resource: 'List the partners (affiliates) in the programme', and it names the filter dimensions. However, it does not distinguish itself from the very similar sibling dub_list_partner_applications, which an agent could easily confuse with partner listing.

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?

'by status, country or email' implies a filtered listing, but there is no explicit when-to-use guidance, no mention of the confusable sibling dub_list_partner_applications, and no statement of preconditions. Usage is only implied.

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

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

readOnlyHint=true already covers the safety profile, and the description adds no behavior beyond it: no pagination semantics, no note on default status filtering, no indication of what 'status' values mean. The 'Dub: GET /payouts' line is an API-mapping aid, 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 short sentences with the purpose front-loaded and no filler. The endpoint reference is the only marginally expendable element, but it is compact.

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 annotations, the description is minimally sufficient, but it omits any mention of filtering/pagination behavior or result shape, and an agent gets no help distinguishing payout listings from commission listings.

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 optional filters (page, pageSize, status, partnerId) are already documented in the schema. The description adds no extra meaning such as allowed status values or pagination defaults, 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 clear verb+resource ('List partner payouts and their status'), so an agent knows what the tool returns. It does not distinguish itself from neighbors like dub_list_commissions or dub_list_partners, which also list partner-related financial/entity data.

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 by the name; there is no statement of when to prefer this over dub_list_commissions or how status/partner filtering should drive the choice. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the REST endpoint (GET /tags) and that the tags are for organising links, but it does not disclose pagination behaviour, ordering, authentication needs, or return shape.

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, followed by the endpoint mapping. 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?

For a simple read-only list endpoint with fully documented parameters and a readOnlyHint annotation, the description is mostly complete. It omits return-value details (no output schema exists), but the complexity is low enough that this is a minor gap.

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

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

Schema description coverage is 100%, so the schema fully documents page, search, and pageSize. The description adds no parameter details beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb (list) and resource (tags) with the scope of organising links, so the agent knows what it returns. It does not explicitly distinguish itself from siblings such as dub_create_tag or other list endpoints, so it falls short of 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?

Provides no when-to-use guidance, prerequisites, or alternatives. The purpose implies it retrieves tags, but nothing tells the agent when this tool is preferable to dub_create_tag or another list operation.

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

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

Annotations already declare destructiveHint=true, and the description adds nothing beyond that: it does not say whether the rejection is reversible, whether the applicant is notified, what state the application moves to, or whether permissions are required. The API endpoint reference is the only extra detail and carries little behavioral 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 short sentences with the action front-loaded and no wasted prose. The 'Dub: POST /partners/applications/reject' line is compact but largely redundant for an agent that never constructs raw HTTP calls.

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 mutation tool with no output schema, the definition covers what is needed to invoke it, and the destructiveHint annotation carries the safety profile. It remains thin on consequences of the destructive action, which is the main outstanding 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% for the single applicationId parameter, so the schema already documents it fully. The description adds no syntax, format, or sourcing guidance beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (reject) and resource (application to join the partner programme), and the verb itself cleanly separates it from the dub_approve_partner_application sibling. An agent can identify the action 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?

There is no when-to-use or when-not guidance, no mention of the approve alternative, and no prerequisites such as required partner-programme state. The only usage signal is the implied context that this handles rejections rather than approvals.

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 supply only destructiveHint=true, so the description carries most of the behavioral burden. It signals a mutation of destination/key/tags/archived state, but says nothing about partial-update behavior (whether omitted fields are preserved), permission requirements, or that tag changes replace existing tags — a notable gap given the destructive hint.

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 mutating action comes first. The 'Dub: PATCH /links/{linkId}' clause is mildly redundant but cheap and useful for API-level context.

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 7-parameter mutation tool with only a destructiveHint annotation and no output schema, the description is thin — it covers the main field categories but not safety, auth, or response expectations. The 100% schema coverage offsets much of this, keeping it at minimum-viable adequacy.

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; baseline is 3. The description names only four of the seven fields (omitting title and comments) and adds no syntax or format 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?

The description names a specific verb and resource ('Change a link's ...') and enumerates the mutable fields, plus the underlying API route, so the agent knows exactly what operation this is. It is distinguishable from sibling create/delete/get link tools by the 'change' semantics, though it never explicitly contrasts 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 versus dub_create_link, dub_delete_link, or dub_get_link, and no mention of prerequisites or that at least one updatable field must be supplied. Usage is only implied by the verb.

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