dub

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

Annotations supply destructiveHint=true, so the safety bar is lower, and the description earns credit by disclosing the concrete consequence of approval: the partner gains links and starts earning commission. It stops short of saying whether the action is reversible or what state the application must be in.

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

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

Three short sentences, front-loaded with the action and its consequence, with the endpoint appended as useful orientation. No filler, though the endpoint string adds little for an agent that already has the tool bound.

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

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

For an irreversible-ish mutation with no output schema and only a destructiveHint annotation, the description covers the effect but omits reversibility, idempotency, required application state, and permission needs. It is adequate but leaves the caller to infer operational constraints.

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 nothing beyond that. Baseline 3 applies when the schema carries the parameter semantics.

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 ('Approving an application to join the partner programme') and even notes the downstream effect. It is clear what the tool does, though it never names its obvious sibling dub_reject_partner_application, so sibling differentiation is left to inference.

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

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

Usage is implied by the name and the described consequence, but there is no explicit when/when-not guidance and no pointer to the counterfactual action (reject) or any prerequisite state (e.g. the 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful cost/latency context ('cheaper than listing') and the underlying endpoint, but says nothing about return format, grouping result shape, or 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?

Three compact sentences, front-loaded with the core purpose and zero filler; the cost rationale and endpoint reference are each a single 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?

No output schema exists, but 'only need totals' plus the explicit grouping dimensions adequately convey the return shape for a count tool. Minor gap: no statement of whether an ungrouped call returns a single total by default.

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 are already documented with their own descriptions including the groupBy enum. The description adds only a high-level restatement of the grouping dimensions; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (count) and resource (links) plus the filter/grouping scope, and explicitly contrasts itself with listing ('cheaper than listing when you only need totals'), which separates it from dub_list_links. An agent can pick it correctly without opening the schema.

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

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

Gives a clear selection condition ('when you only need totals') and implicitly names the alternative (listing), but does not name dub_list_links or state when-not to use it (e.g., when full link records are required).

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 destructiveHint=true, and the description adds nothing beyond the HTTP endpoint (POST /folders). It does not disclose permission requirements, duplicate-name behavior, what the accessLevel default is, or what the call returns. With annotations present, the description is expected to add context and does not.

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 with zero filler. The trailing "Dub: POST /folders" is of marginal value to an agent but costs little.

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

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

For a simple three-parameter create tool with full schema coverage and no output schema, the description covers the essentials of what the tool does. It falls short on when to use it and on the behavioral implications of the declared destructiveHint, which an agent would want before creating workspace-organizing resources.

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

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

Schema description coverage is 100% and all three parameters (name, accessLevel, description) are documented in the schema, so baseline 3 applies. The description provides no additional parameter meaning, such as explaining when to set accessLevel or what each enum value implies.

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") and adds scope with "for grouping links," which tells the agent what folders are for relative to the link-centric siblings. It does not explicitly distinguish itself from dub_create_link or dub_create_tag, but the resource noun 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?

There is no guidance on when to create a folder versus using tags (dub_create_tag) or how folders relate to link organization, and no mention of prerequisites such as workspace permissions. 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 supply destructiveHint=true, so the safety profile is partly covered by structured data. The description adds only the API endpoint mapping ("Dub: POST /links"), which is developer trivia rather than agent-relevant behavior; it says nothing about what happens on key collisions (Dub upserts), permissions, rate limits, or side effects.

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, front-loaded sentences with no padding; the essential creation semantics come first. The trailing "Dub: POST /links." is arguably noise for an agent but is brief enough not to 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?

For a simple one-required-parameter create, the definition is minimally viable and the schema carries parameter detail well. However there is no output schema and the description omits the return shape/ID, error semantics, and the upsert-on-existing-key behavior — gaps an agent would hit in practice.

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 every one of the nine parameters is documented inline. The description's single parameter note about `key` merely restates the schema's own text ("Omit for a random one"), so it adds no meaning beyond structured data — the baseline 3 applies.

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

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

The description states a specific verb and resource ("Create a short link") and the parameter hint about `key` confirms the creation semantics. It is trivially distinguishable from dub_update_link, dub_get_link and dub_list_links by name, though it never explicitly contrasts itself with any 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 only guidance is parameter-level ("Omit `key` to let Dub generate one"), which is a value choice, not a when-to-use instruction. There is no statement of when to prefer this over dub_update_link, nor any prerequisites such as required scopes or workspace context.

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

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

The annotations declare destructiveHint=true, but the description says 'Create a tag', which is an additive operation. This is a direct contradiction: creation is not destructive. Additionally, the description does not disclose authentication needs, duplicate-tag behavior, or side effects.

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. Every word contributes, and the endpoint information is compact. No filler or redundancy.

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

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

For a simple two-parameter create tool with full schema coverage and no output schema, the description covers the basic purpose. However, it fails to address behavioral gaps around creation semantics, duplicate handling, or permissions, and the annotation contradiction leaves the agent with an unclear safety profile.

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

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

Schema description coverage is 100%, so both parameters (name, color) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, which is the baseline expectation when schema coverage is complete.

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 and resource: 'Create a tag'. It also provides the HTTP endpoint. However, it does not differentiate from siblings like dub_list_tags or dub_create_folder beyond the tool name itself.

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 'for organising links' implies a general use case, but there is no explicit guidance on when to use this tool versus alternatives such as dub_list_tags or dub_create_link. No prerequisites or exclusions 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 destructiveHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: deletion is immediate, breaks the URL, and irreversibly destroys analytics — exactly the impact information an agent needs before invoking a destructive tool.

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

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

Three short sentences, all front-loaded and information-dense: what it does, what breaks, and the underlying API route. No filler.

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

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

For a single-parameter destructive tool with no output schema and annotation coverage of the safety profile, the description supplies the essential irreversibility context. Minor gaps: no error behavior (e.g., link not found) or auth requirements.

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 (linkId) and schema description coverage is 100%, so the schema already documents it. The description adds no format, lookup, or ID-sourcing guidance, so this sits at the 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 (Delete) and resource (short link) and goes further by naming the observable consequence: the URL stops resolving. It is unambiguous against siblings such as dub_update_link or dub_get_link.

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 destructive consequence implies when to use it, but the description never states prerequisites, exclusions, or alternatives (e.g., updating vs. deleting a link). Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds that results are aggregated and dimension-grouped and cites the underlying endpoint, but says nothing about result limits, pagination, or how defaults (e.g. event=clicks, a default interval) are applied.

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 sentences with zero filler, and the core capability and grouping model are front-loaded before the endpoint reference. Nothing could be cut without losing 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?

All parameters are optional and fully documented in the schema, so invocation risk is low, and the description conveys the grouped/aggregated return shape despite there being no output schema. It could still say more about the response structure for the various groupBy values, but coverage is solid for a read-only reporting tool.

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

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

Schema description coverage is 100%, so all ten parameters are already self-documented, and the description's mention of dimensions and event types largely mirrors the schema's groupBy and event enums. It adds no syntax, format, or interaction 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 ('Get aggregated click, lead and sale analytics') plus the grouping model ('grouped by a dimension such as country, device, referer or top links'), which is more than a restatement of the name. It does not, however, distinguish itself from the sibling dub_get_partner_analytics, leaving that differentiation to inference.

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

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

'The main reporting read' implies this is the default analytics entry point, but no explicit when-to-use or when-not-to-use guidance is given. The agent must infer that dub_get_partner_analytics covers the partner-side case; the description never names or excludes it.

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 safe read, so the bar is lower. The description adds that attribution data is included in the response, which is useful context, but it discloses nothing about not-found behavior, auth requirements, or response shape beyond that one field mention.

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

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

Two short sentences, front-loaded with the operation and payload, followed by the REST endpoint reference. No filler, though the endpoint string is low-value for an agent that never sees raw HTTP.

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 annotations covering safety, the description is nearly sufficient. Because there is no output schema, the brief note that attribution comes back with the customer is doing real work in setting response expectations, though it is thin given no field-level detail.

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

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

Schema coverage is 100% with a single documented parameter, so the schema already fully explains customer_id. The description adds no syntax, format, or sourcing detail about the id beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single customer') and adds the returned payload scope ('with their attribution'). The word 'single' implicitly distinguishes it from the sibling dub_list_customers, but that alternative is never named, so the differentiation is left to inference.

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

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

Usage is implied by the singular-resource framing and the required customer_id, which together signal a lookup-by-id operation. There is no explicit statement of when to use this versus dub_list_customers, and 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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that the description adds only an API route reference, saying nothing about not-found behavior, whether any of the four optional identifiers must be supplied, or rate limits. No annotation contradiction, but virtually no added 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?

One front-loaded sentence with the identifier options first and the route reference last. Zero filler; every clause carries information.

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

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

With zero required parameters, an agent needs to know the valid identifier combinations, and the description supplies them. No output schema exists, though the description would ideally note the not-found case given four all-optional parameters.

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 genuine meaning the schema does not: it frames linkId, externalId, and the domain+key pair as alternative lookup strategies, not just four independent fields. It stops short of stating that only one strategy should be used per call.

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 link), and enumerates the three accepted identifier schemes. The word 'single' plus the named key combinations cleanly separate it from dub_list_links and dub_count_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?

The three lookup modes imply 'use this when you already have an identifier', which is useful, but the description never says when to prefer this over dub_list_links or what to do when the link does not exist. Usage is left implicit 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. The description adds the metric scope (clicks, leads, sales, revenue) which is useful context, but says nothing about return format, pagination, aggregation behavior, or required scopes for a 5-parameter analytics query.

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 scope and metric list front-loaded before the endpoint reference. Nothing extraneous.

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 analytics query with fully documented parameters and no output schema, the description supplies the essentials and even hints at the returned metric dimensions. It would be stronger with a note on default window behavior and the grouping/timeseries options, but nothing critical is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (including the enum values for interval and the start/end-vs-relative-window distinction). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get analytics for the partner programme') and enumerates the metrics returned (clicks, leads, sales, revenue per partner). This distinguishes it in scope from the sibling dub_get_analytics, though it never names that 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 phrase 'for the partner programme' implies when this tool applies versus general analytics, but there is no explicit when-to-use guidance, no stated defaults for the optional time parameters, and no mention of the dub_get_analytics alternative. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds only the API endpoint (GET /commissions); it says nothing about pagination behavior or result shape, which matters for a paginated list endpoint with page/pageSize parameters.

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

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

Two tight sentences with no filler; the scope and filter dimensions are front-loaded and the endpoint note is a single compact 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?

For a read-only list tool with zero required params, full schema coverage, and annotations covering safety, this is nearly complete. The only gap is absence of any note on pagination/results behavior, which the lack of an output schema leaves unaddressed.

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 7 parameters are already documented in the schema, including the interval enum. The description restates the filter dimensions without adding syntax, defaults, or combined-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 partner commissions') plus the filterable dimensions, which is enough to distinguish it from near siblings like dub_list_payouts or dub_get_partner_analytics. It does not explicitly name or contrast with those siblings, 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 ('by partner, status, customer or time window') implies when the tool is useful, but there is no explicit when-to-use, when-not-to-use, or alternative ('use dub_list_payouts for X'). Usage is inferable rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main marginal contribution is the scoping context that results are link-attributed customers, plus the GET endpoint reference. It says nothing about pagination behavior, result ordering, or how multiple filters combine, so it adds only modest value 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 short sentences, the purpose and filter keys front-loaded. The trailing 'Dub: GET /customers.' is minor metadata but cheap and harmless; there is no padding 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 parameterless-required list endpoint with no output schema, an agent still lacks return-shape and pagination expectations (page/pageSize exist in schema but the description never mentions paged results). What is present is accurate and sufficient to invoke the tool, but not sufficient to predict its 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%, with every one of the six parameters documented inline, so the baseline is 3. The description echoes three of the filter keys already described in the schema and adds no semantics (e.g., AND/OR behavior between filters) beyond what structured data 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 (customers), and clarifies that these are customers Dub has attributed to links, which goes beyond a tautological restatement of the name. It also names the filter keys (email, external id, link), letting an agent distinguish it from the singular dub_get_customer without opening the schema. It stops short of explicitly contrasting itself with 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 mention of filtering 'by email, external id or link' implies when this tool is useful (bulk retrieval or lookup by identifier) but never states when-not to use it or names dub_get_customer as the single-record alternative. 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description adds only the upstream endpoint reference (GET /domains). It says nothing about pagination behavior, result caps, or workspace scoping beyond 'configured on the workspace'. With annotations carrying the safety burden, this is adequate but thin.

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

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

Two short sentences, front-loaded with the action and scope; the endpoint note is a compact, useful trailing detail. 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?

No output schema exists, so some return-shape guidance would help, and the description offers none. Combined with no usage routing, it is the minimum viable for a simple read-only list whose parameters are fully documented 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 page, search, archived, and pageSize are all documented in the schema itself. The description adds no syntax, defaults, or interaction details 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 and resource ('List the short domains configured on the workspace'), which lets an agent distinguish it from dub_list_links, dub_list_folders, and dub_list_tags. It does not explicitly name a sibling or contrast with them, but the resource is unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives or how it relates to the other list_* tools. The agent must infer that this is the entry point for enumerating domains and that search/archived/page params control filtering.

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

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

readOnlyHint=true already declares this a safe read operation, so the annotation carries the safety burden. The description adds the useful 'row-level vs aggregate' behavioral framing, but says nothing about pagination behavior or the shape of returned rows.

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

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

Two short sentences with zero filler; the key scoping distinction is front-loaded before the endpoint reference. Every sentence earns its place.

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

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

For an 8-parameter, all-optional listing tool, the description captures purpose and the crucial semantic distinction from aggregates, while the schema fully covers parameter details. Since no output schema exists, a brief note on returned row shape would have added value, but nothing needed for a correct call is missing.

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

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

Schema description coverage is 100% and all 8 parameters are documented in the schema (enums, ranges, pagination). The description adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List individual click, lead and sale events') and immediately scopes it against the aggregate alternative ('rather than aggregates'). An agent can distinguish it from dub_get_analytics 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?

The phrase 'rather than aggregates — the row-level detail behind the analytics' gives clear context for when this tool is the right choice versus an aggregated analytics call. It does not name dub_get_analytics explicitly or give exclusions, but the contrast is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only that access levels are included in the result, with no detail on pagination behavior, filtering semantics, or empty-result handling, so it adds modest value beyond structured fields.

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 prose. The trailing 'Dub: GET /folders' is developer-facing filler but negligible in size.

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 three optional parameters are covered by the schema and there is no output schema, so the description only needs to frame the operation. It does so adequately, but says nothing about result ordering, pagination consequences, or what an empty list means.

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 by the schema itself. The description adds no syntax, defaults, or interaction notes 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 (link folders) plus what it returns (access levels), which distinguishes it from dub_create_folder and dub_list_links without opening a schema. It does not explicitly name a sibling, so it falls just short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as searching or fetching individual folders, and no prerequisites or exclusions are stated. The REST endpoint reference is not usage guidance for an agent.

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 main job is filling in non-obvious behavior. It adds the underlying endpoint (Dub: GET /links), which is useful context, but says nothing about default pagination, the default for showArchived, or total-count metadata. Adequate but thin for a 7-parameter list 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 short sentences with zero filler, and the ungated verb+resource leads before the optional filter caveat. Nothing could be removed without losing information.

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

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

With no output schema, the description should at least signal the return shape (a paginated list of link objects) and pagination defaults, but it does not. All seven parameters being optional and the endpoint hint partially mitigate this, yet an agent still can't predict result structure or default page size from the definition alone.

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, domain, search, folderId, pageSize, tagNames, showArchived) is already documented in the schema. The description merely restates the categories of filters, adding no syntax, defaults, or matching semantics beyond what's structured. 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+resource ('List short links') and enumerates the four filter axes, which cleanly distinguishes it from siblings like dub_count_links, dub_get_link, and dub_list_domains. An agent can identify this as the retrieval tool 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 filter list implies when this tool is appropriate (browsing/searching links with optional narrowing), but there is no explicit when-to-use or when-not-to-use guidance and no pointer to alternatives. It never clarifies the relationship to dub_count_links or dub_get_link for single-link retrieval.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds one genuinely useful behavioral fact — only *pending* applications are returned, not the full set — but says nothing about pagination defaults, result ordering, or auth requirements.

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

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

Two short sentences, front-loaded with the scoping qualifier. The trailing 'Dub: GET /partners/applications' is REST endpoint bookkeeping of marginal value to an agent but costs little.

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

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

For a 2-param read-only list tool this is close to adequate, and annotations cover safety. However with no output schema the description does not hint at the return shape, and pagination behavior (defaults, max size) is left entirely 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 coverage is 100% with both page and pageSize documented inline including ranges and 1-based indexing, so the schema carries the parameter burden. The description adds no pagination semantics beyond what the schema already states; baseline 3 applies.

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

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

States a specific verb (List) and resource (applications to join the partner programme) with a narrowing scope qualifier (pending). An agent can tell this apart from dub_list_partners and the approve/reject siblings, though the description never names those alternatives 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 guidance, no prerequisites, and no mention of alternatives such as dub_list_partners (all partners) versus this tool (pending applications only). The 'pending' qualifier implies scope but the agent must infer when to reach for this versus the approve/reject flows.

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 that results can be filtered by status/country/email plus the underlying endpoint (GET /partners). It says nothing about pagination behaviour or result shape, so it adds only modest context beyond the annotation.

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

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

A single front-loaded sentence covering purpose and filters, plus a short endpoint reference. Nothing is wasted, though the endpoint note is marginal 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 no output schema and full schema coverage, the description is adequate but thin: it does not characterize pagination, default page size, or how an empty result should be interpreted. The mention of a non-existent 'country' filter also leaves a small correctness 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 all five parameters are documented in the schema, establishing a baseline of 3. The description adds no syntax or format detail, and its filter list ('status, country or email') omits the free-text 'search' parameter and names a 'country' filter that does not exist in 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 ('List the partners (affiliates) in the programme') and names the filter dimensions, so an agent knows this returns existing partners rather than applications. It does not explicitly name the sibling dub_list_partner_applications to disambiguate the two, which keeps it below 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 phrase 'in the programme' implies this is for already-enrolled partners as opposed to applicants handled by dub_list_partner_applications, but that distinction is left to inference. No explicit when-to-use or when-not-to-use guidance 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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds that status is included in results, which is mild value, but it discloses nothing about pagination behavior, filtering semantics, or auth requirements beyond what annotations and schema already 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, front-loaded with the purpose, with no redundancy. The trailing 'Dub: GET /payouts' is a compact API mapping that adds minor orientation value rather than padding.

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

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

For a four-parameter list tool with no output schema, the description covers the core purpose but omits return shape, pagination expectations, and how the status/partnerId filters interact. Adequate but with clear gaps for an agent needing to call it precisely.

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 page, pageSize, status, and partnerId are fully documented in the schema itself. The description's mention of 'status' loosely echoes the status filter but adds no format or syntax 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+resource ('List partner payouts') plus the returned attribute ('their status'), so the agent knows exactly what the tool produces. It does not, however, contrast with close siblings like dub_list_commissions or dub_list_partners, so differentiation is left implicit.

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 alternatives such as dub_list_commissions, nor any mention of prerequisites or typical contexts. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered structurally; the description's 'List' merely restates it. It adds no behavioral context such as pagination behavior, default page size, or whether results are workspace-scoped, leaving the description with essentially no value 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 short sentences, front-loaded with the purpose. The trailing 'Dub: GET /tags.' endpoint reference is low-value but harmless and brief.

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 three-parameter schema, the description is minimally viable. It omits any indication of what a returned tag looks like or how paging is handled, and with no output schema the description leaves return semantics entirely unexplained.

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 (page, search, pageSize) fully documented in the schema, so the baseline of 3 applies. The description adds nothing—no default paging behavior or search semantics—beyond what the schema already 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 ('tags') plus the purpose ('for organising links'), which is enough to distinguish it from siblings like dub_list_links or dub_list_folders. It stops short of explicitly contrasting with any sibling, so it is clear but not maximally 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 description gives no when-to-use guidance, no conditions, and no mention of alternatives (e.g., dub_create_tag when the tag doesn't exist, or dub_list_links for per-link tags). The 'organising links' phrase implies context but does not route the agent.

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

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

The destructiveHint=true annotation already tells the agent this is a destructive operation, and the description merely restates 'reject' without adding behavioral context such as irreversibility, whether the applicant is notified, or whether a rejected application can be reinstated. The only extra information is the underlying endpoint mapping, which is not behaviorally useful to an agent.

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; the second sentence is only an API endpoint reference, which is mild filler but does not obscure the main point.

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 one-parameter destructive tool the annotations and schema cover most of what an agent needs, but the description omits the one thing annotations cannot convey here: the consequence of rejecting and whether it is reversible. 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% for the single applicationId parameter, so the schema already documents it fully. The description adds no format, sourcing, or constraint detail 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), which is a genuine improvement over the bare title and distinguishes it from sibling write tools. It does not explicitly contrast itself with dub_approve_partner_application, but the reject/approve opposition is self-evident.

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 the alternative dub_approve_partner_application, no precondition (e.g. application must be pending), and no exclusions. 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.

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

Annotations already declare destructiveHint=true, so the risk profile is partly covered. The description adds the PATCH endpoint and the mutable field set, but says nothing about partial-update semantics or that changing 'key' can break previously distributed links — useful context that is missing for a destructive mutation tool.

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

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

Two short sentences, front-loaded with the mutable fields and followed by the API mapping. Nothing is wasted and the most decision-relevant information 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 destructive PATCH with no output schema and a fully described input schema, the definition is minimally sufficient — an agent knows what it can change. It omits the merge-vs-replace behavior and consequences of key changes, which leaves a gap 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 every parameter including 'tagNames' replace-semantics and 'archived' is already documented in the schema. The description only restates four of the seven fields and adds no syntax or format detail, so baseline 3 applies.

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

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

States a specific verb (change) plus the resource and the exact fields it can mutate, which distinguishes it from dub_create_link, dub_delete_link and dub_get_link without opening a schema. It stops short of explicitly naming a sibling, 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?

No when-to-use or when-not-to-use guidance, no mention of prerequisites such as needing the link to exist or having write scope. The field list implies the edit use case but nothing routes the agent between this and dub_create_link for correcting a link.

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