Clickwise Affiliate Network

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses the auth requirement (own Clickwise affiliate API key via X-API-Key or Bearer), the account scoping ('acts only on your account'), and the outcome model ('approved or pending'). That is exactly the behavioral context an agent needs before invoking a mutation.

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 sentences, front-loaded with the action and the ID source before auth details. Dense and largely waste-free, though the parenthetical about ID provenance is a little packed for a reader scanning quickly.

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

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

With no output schema, the description correctly supplies the return status (approved or pending) and the auth/account constraints. The remaining gap is the zero-required-parameter ambiguity (must one of program_id/campaign_id be supplied?) and the undocumented campaign_id origin.

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 0% and there is no type/format documentation, so the description must carry the load. It gives useful provenance for program_id (comes from list_my_programs with include_available) but says nothing about where campaign_id originates, its valid form, or whether exactly one of the two is required.

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 ('Ask to join a program') and immediately anchors the identifier to the sibling that produces it (list_my_programs with include_available). An agent can distinguish this from list_my_programs, find_affiliate_programs, and the request_* siblings without opening any schema.

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

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

Explains where program_id comes from and that campaign_id is an accepted alternative, which tells the agent how to be ready to call it. It does not state when NOT to apply or what the alternative route is if the agent lacks an ID, so it stops short of full when/when-not guidance.

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

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

Annotations establish the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=false), and the description adds real context beyond them: auth mechanism (X-API-Key header or Bearer), account scoping ("acts only on your account"), per-item failure isolation ("a failed item never blocks the others"), and the dedup rule that the same program+subid returns the same 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?

A dense but efficient two-sentence block, front-loading the primary use case and following with the alternative and constraints. Every clause (dedup, per-item status, auth header, account scope) earns its place, though the sentence is long.

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, yet the description covers the critical return-relevant behavior (each item reports its own status) and the auth prerequisites. Combined with the annotated idempotency guarantee, an agent has enough to call it correctly; only the batch-size limit and field precedence are 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?

Top-level schema description coverage is 0% for the single `links` array, so the description must carry the load; it explains item granularity, deep-linking via landing_url, and the program/subid keying rule. However the nested property descriptions (subid, program_id, campaign_id, landing_url) already document individual fields, and the description does not clarify program_id vs campaign_id precedence or the maxItems=20 limit, so compensation is only partial.

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 (create tracking links for approved programs), defines the one-per-item scope, and names the sibling it is not (request_tracked_links). An agent can distinguish it from request_tracked_links 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?

Explicitly says when to use it (you already hold a Clickwise affiliate API key and are approved in the programs) and routes elsewhere when not ("Without an account use request_tracked_links"). The alternative and its selecting condition are both named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuinely new context the annotations do not carry: no signup/account is required, and results are ranked by fit against the described publisher. It stays silent on result size, pagination, and rate limits, keeping it just short of a 5.

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

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

Two sentences, both front-loaded: the eligibility trigger and the ranking behavior come first, the sibling routing second. No filler, no restatement of the tool name, and the reader can act after the first 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 an 11-parameter, all-optional, read-only search tool with no output schema, the description is nearly sufficient: eligibility, ranking semantics, and sibling disambiguation are all present. The gap is that it never hints at what comes back (ranked program list with fit signals) or how the default limit of 8 shapes a response, which an agent choosing argu

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 91% across 11 parameters, so the schema already documents topic, channel, country, network, publisher_url, traffic figures, and include_unready. The description only implicitly echoes topic/channel/publisher_url ('described site, app, newsletter or social channel') without adding format, defaults, or interaction rules beyond what the schema states. Baseline 3 is the correct ceiling here.

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

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

The description states a specific verb and resource ('ranks live programs by fit') and names the input that drives the ranking ('for a described site, app, newsletter or social channel'). It also names the two sibling tools it is not, so an agent can distinguish it without opening any schema.

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

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

It gives an explicit trigger ('Use this first when someone without a Clickwise account asks which merchants to promote') and routes to alternatives with their conditions: list_programs for whole-catalogue paging and list_my_programs for already-approved programs. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: a fixed one-hour validity window, a snapshot_stale marker for older counts served up to 7 days, and the explicit exclusion of affiliate data and amounts. These caching and data-scope traits are exactly what an agent needs and cannot infer from the annotations.

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

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

Three short, front-loaded sentences with no filler: what it returns, how fresh it is, and what it excludes. The freshness constraint appears before the caveats, which is the right ordering.

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

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

With no output schema, the description carries the return-shape burden and discloses the staleness flag and exclusion of amounts. It stops short of saying what the counts actually comprise (e.g. total vs. per-category GTINs), which leaves a small ambiguity about the payload.

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?

The tool takes no parameters, so the baseline is 4. The description correctly implies a parameterless call and instead spends its text on the data semantics that matter for this tool.

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: it returns public GTIN catalog counts as of a snapshot time. No sibling tool returns statistics, so it is trivially distinguishable from list_/get_ tools that return records. The reference to the equivalent REST endpoint pins down the exact data set.

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 resource (use it to read catalog counts), but there is no explicit when-to-use or when-not guidance, nor any named alternative. With a flat catalog of siblings and no overlap, the absence of exclusions is a minor gap rather than a hazard.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that the response is a full record in the requested language; it says nothing about not-found behavior, permissions, or rate limits, so it adds modest value on top of annotations.

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

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

Two front-loaded sentences with no filler, the identification method ('by its slug') stated first. The trailing 'etc.' makes the return-field list slightly vague but it is efficient overall.

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 read with no output schema, the description gives the identifying key, the language option, and a sample of returned fields, while annotations cover safety. Nothing critical is missing for correct invocation, though not-found/error behavior is unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that 'slug' identifies a single deal and that 'lang' selects the response language, covering both parameters beyond the bare schema. It doesn't state the enum values or the default, which are visible in the schema anyway.

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 the full record for a single deal by its slug'), which clearly separates it from list_deals and search_products. It doesn't explicitly name the sibling it contrasts with, so sibling differentiation is implied rather than stated.

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

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

Usage is implied: fetch one deal when you already have its slug, versus list_deals for browsing. There is no explicit when-to-use/when-not guidance or named alternative, so it stays at the minimum viable level.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description adds real behavioral context beyond them: it creates a provisional affiliate, email is optional, the account is claimed later for payout, and it returns multiple output formats. It doesn't spell out the consequence of repeat calls (non-idempotent side effects) or whether the provisional account persists, which keeps it from a 5.

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

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

Three sentences, front-loaded with the usage condition and the sibling routing, and every sentence carries information. It is densely packed but not wasteful; the return-format detail and the alternative routing both earn their place.

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

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

With 8 optional parameters, no required inputs and no output schema, the description fills the important gaps: it explains the side effect (provisional account + tracked links), the output shape (cards, HTML embed, JSON feed) and the fallback tools. An agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description adds a little meaning by clarifying that claim_email is optional and tied to later payout, but the remaining parameters get no additional semantics. Baseline 3 is correct 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 and resource (creates a provisional Clickwise affiliate and tracked links, returns cards, an HTML embed snippet and a JSON feed). It explicitly distinguishes itself from request_tracked_links and create_tracking_links, so an agent can route correctly without opening any schema.

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

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

Gives an explicit condition for use (a publisher without an account wants links ready to render) and names two alternatives with the selecting condition: request_tracked_links for plain links, create_tracking_links with an existing API key. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful behavioral note that it returns the 'full record' (contrasting with the partial list view), but says nothing about return format, caching, or missing-slug behavior.

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

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

A single front-loaded sentence with zero filler; the lookup key follows immediately after the purpose. Nothing is wasted.

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

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

With no output schema and a simple read tool, the description is close to sufficient, but it leaves the lang parameter unexplained and does not state that the slug originates from list_news. Adequate but with recognizable gaps.

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 0%, so the description must carry the load, but it only explains the 'slug' parameter and gives no semantics for 'lang'. The enum values and default are visible in the schema, but the description never confirms that lang selects the localized article (and what happens with unsupported translations).

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 ('full record for a single news article'), with the lookup key ('by its slug') made explicit. The word 'single' implicitly separates it from the sibling list_news, though the sibling is never named.

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

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

The phrase 'by its slug' implies the caller must already have a slug (presumably from list_news), so usage is implied rather than stated. There is no explicit 'use this instead of list_news when...' routing guidance or precondition statement.

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 read-only/idempotent/non-destructive, but the description adds substantial context beyond them: the exact privacy boundary (never returns account numbers, PayPal addresses, postal or tax data), the masking behavior (bank account shows only last 4 digits), and the authentication requirement (X-API-Key header or Bearer). That is meaningful behavioral detail an agent cannot derive from 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?

Front-loaded with the usage trigger, then the return payload, then privacy and auth notes. Every clause carries information, though the first sentence is a dense multi-item list that could be broken up; no filler or redundancy.

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

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

With no output schema, the description carries the full burden of describing return values, and it does so field-group by field-group. Auth modality, account scoping, and privacy limits are all covered, so an agent has everything needed to call 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?

The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% and there is nothing for the description to disambiguate at the input level.

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 payment status) and then enumerates exactly what the response covers: approved-but-unpaid commission, commission pending review, next payment estimate with threshold, and payment method type. This is clearly distinguishable from reporting siblings like get_performance_report or list_conversions.

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

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

Gives an explicit trigger condition ('Use this when an affiliate asks when they get paid'), which is clear and actionable. It does not name any alternative tool or state when NOT to use it, so it falls short of the 5-level when/when-not/alternatives framing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real behavior an agent cannot infer: the auth mechanism (X-API-Key or Bearer), that it acts only on the caller's own account, the 366-day cap with a 30-day default, and that daily/weekly/monthly series include empty periods.

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

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

A single dense sentence with no filler, and the highest-value content (what is returned) is front-loaded. The run-on auth clause at the end is slightly heavy but still earns its place.

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

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

No output schema exists, so the description carries the burden of describing the return shape, and it does (grouped conversion and commission figures, empty periods retained). Remaining gaps are the filter semantics of subid/status, which are minor for a read-only report.

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 only 40% and 5 parameters exist, so the description must compensate. It usefully covers group_by values and the date window, but frames subid and status only as grouping dimensions rather than explaining their filter behavior, leaving that half of the parameters thin.

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 ('Your conversions and commission... grouped by day, week, month, subid, campaign or status') with the aggregation dimensions and window spelled out. An agent can distinguish this reporting tool from list_conversions or get_catalog_stats 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 operational context (default last 30 days, 366-day max, API key required) but never says when to choose this over list_conversions or how the subid/status filters interact. Usage is implied rather than contrasted with alternatives.

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

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

It goes beyond the annotations by disclosing real behavioral traits: the URL is signed, links are Clickwise /dl/-tracked, the operation is idempotent in a user-visible way ('the same request returns the same URL'), and external factors (freshness, permissions, assignments, delivery caps) can affect the result. This aligns with idempotentHint=true and readOnlyHint=false without contradicting them.

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?

Four sentences, each carrying distinct information (capability, return value, idempotency, prerequisites), with the core action front-loaded. Slightly dense but 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 three-parameter, no-output-schema mutation tool, it covers the action, return artifact, idempotency, auth requirement and constraints. The main gap is the undocumented category parameter and any indication of error or cap-exceeded behavior.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It documents country ('one country') and format ('json, csv, tsv or xml') but never mentions the category parameter, leaving one of three parameters completely unexplained.

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

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

The description gives a specific verb-and-resource pairing ('Create or refresh a GTIN product feed') plus the concrete outcome (a signed URL with tracked product links), so the agent knows exactly what the tool produces. It stops short of differentiating itself from siblings such as get_monetization_feed, which could plausibly return similar feed artifacts.

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 sets preconditions (authenticated affiliate API key, one country, freshness/permissions/assignment/delivery-cap constraints) which is useful context. However, it never states when to prefer this tool over get_monetization_feed or get_catalog_stats, and gives no explicit exclusion or alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds that access is gated by an access secret, which is useful auth context, but says nothing about what happens on an invalid/expired secret or whether results are eventually consistent.

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 naming the action, the resource, and the return contents. No filler or redundancy.

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

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

With no output schema, the description's enumeration of returned fields (RefId, review status, issued links) is valuable and partially fills that gap. However, it omits error/authorization failure behavior and does not explain application_id, leaving a read tool with required auth reasonably but not fully specified.

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 0%, so the description carries the full burden. It hints that the lookup is keyed by 'its access secret', loosely mapping to access_secret, but application_id is never mentioned, explained, or linked to the secret.

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 ('link request') and enumerates the payload items returned (affiliate RefId, review status, issued links). It contrasts implicitly with creation siblings like request_tracked_links and create_tracking_links, though it never names 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as request_tracked_links (to create a request) or create_tracking_links (to issue links). The agent must infer the retrieval role from the 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description goes further by disclosing the auth requirement (own Clickwise API key via X-API-Key or Bearer) and the default 90-day window. It does not explain pagination behavior or result ordering, which keeps it short of a 5.

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

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

Two tight sentences, front-loaded with what the tool returns and followed by the auth constraint. Every clause carries information; only the parenthetical auth detail slightly crowds the core purpose statement.

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

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

With no output schema, the description usefully names the returned fields and the per-subid rollup, and it covers the auth and account-scoping requirements. It stops short of describing pagination limits/defaults, which matters for a 6-param list tool with page_size up to 500.

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 only 33% across 6 params, so the description must compensate and it partially does: status, subid and the date range ('default: last 90 days') are implied. But page and page_size, which govern result volume, get no mention in either place, leaving a real gap.

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

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

States a specific resource (individual conversions) and enumerates the returned fields (status, commission, currency, subid, plus a per-subid rollup), so an agent knows exactly what this tool produces. No sibling tool in the list deals with conversions, so the resource is self-differentiating from get_performance_report and the rest.

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 concrete context — default window of the last 90 days and that it acts only on your own account — which implies when it applies. However it never names an alternative (e.g., get_performance_report for aggregate stats) or states any exclusion, so the when-to-use-vs-sibling decision is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds only the "active" scoping word; it says nothing about pagination behavior or result volume despite limit defaulting to 20 and capping at 100.

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 zero filler; the verb, resource and filter options are all in the first 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 no output schema and annotation coverage of the safety profile, the description is nearly sufficient. The gaps are pagination/result-shape and the fact that the network filter only applies to signed-in affiliates, which matters for correct invocation.

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

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

Schema description coverage is 67%, and the description names four of the six filters (lang, category, country, merchant), matching what the schema already documents for three of them. It omits limit and network entirely, so it neither compensates for the undocumented lang/limit fields nor adds syntax 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?

The description states a specific verb (list) and resource (active Clickwise deals and offers) and names the filter dimensions. It is clearly distinguishable from get_deal (single item) and list_programs, though it does not explicitly contrast itself with those siblings.

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

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

"Optionally filtered by..." implies the retrieval use case, but there is no explicit when-to-use guidance, no mention of when to prefer get_deal or search_products, and no statement of prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description still adds non-obvious behavior: the required auth credential and its exact placement ('X-API-Key header or Authorization: Bearer') and that it 'acts only on your account'. The include_available flag's effect on the result set is also 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?

Front-loads the core purpose and effect, then the alternative, then the auth requirement. The first sentence is dense with semicolon-joined clauses, but every clause carries routing or capability information and nothing is redundant.

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

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

There is no output schema, and the description fills that gap by describing what comes back (link readiness, link count). Auth, account scope, sibling disambiguation, and the optional expansion flag are all covered, so an agent has everything needed 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 only 25% (just 'search'), but the description compensates by explaining include_available's semantics ('add the ones you can apply to') and the default result set ('programs that key is approved to promote'). page and page_size are left to their self-evident names/defaults, which is a minor gap rather than a failure.

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 my programs') plus the exact scope: programs the supplied API key is approved to promote, augmented with link readiness and existing link count. It explicitly separates itself from the discovery siblings find_affiliate_programs and list_programs, so an agent can route without opening any schema.

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

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

Gives a clear trigger ('when you hold a Clickwise affiliate API key and need the programs that key is approved to promote') and names the alternative for the opposite case ('for discovery without an account use find_affiliate_programs or list_programs'). Exclusions are stated, not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and consistency profile is fully covered. The description adds only topical scope, no pagination, ordering, or defaulting behavior, which is acceptable given the annotation coverage but adds little.

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

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

A single front-loaded sentence with no filler; the resource and its scope appear immediately.

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 and 0% parameter description coverage, the description should carry the burden of explaining the returned item shape and filters, but it does neither. For a four-parameter filtered list tool, this leaves an agent guessing about defaults and result structure.

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 0% for four parameters (lang, limit, network, severity), and the description explains none of them. The severity enum (info/warn/critical) loosely maps to the listed news categories, but language, result cap, and network filtering are left entirely undocumented.

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 ('Clickwise news announcements about affiliate programs') and enumerates the content types covered (policy changes, launches, shutdowns, commission updates). It is clear what the tool returns, but it never distinguishes itself from the sibling get_news, leaving the list-vs-get split to inference.

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

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

No when-to-use or when-not-to-use guidance, and no prerequisite or alternative named. An agent facing both list_news and get_news gets no signal about which to pick.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: no API key required and the result set is limited to publicly joinable programs, which materially affects how an agent should interpret results. It stops short of describing pagination termination or result ordering.

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

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

Three short sentences, each carrying distinct information: purpose and filters first, then the auth/visibility fact, then the disambiguation pointer. No filler and nothing buried.

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

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

For a 7-parameter, no-output-schema read tool this covers purpose, filtering, auth requirements and sibling routing, which is most of what an agent needs. The remaining gap is pagination semantics (how many pages, how to know when to stop) and the effect of ready_only's 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 57%, so the schema already documents country, network, merchant and ready_only. The description names three of the seven filters (merchant, category, country) but says nothing about page/page_size or the meaningful ready_only default of true, which changes what the agent gets back.

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 ('browse the whole live catalogue page by page') plus the filterable dimensions, and explicitly distinguishes itself from both find_affiliate_programs and list_my_programs. An agent can route between the three sibling list tools without opening any schema.

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

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

Gives the exact condition for choosing this tool ('when find_affiliate_programs' ranked top matches are not enough') and names the alternative for the other case ('For the programs your API key is approved in use list_my_programs'). When-to-use and when-to-use-something-else are both explicit.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) by disclosing the stateful, multi-turn interview loop and the possible outcomes (follow-up question, approval, decline). It also notes the response carries a status and an access secret needed to continue, which is valuable since there is no output schema. It stops short of stating auth requirements or what happens to abandoned/duplicate applications.

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

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

Two tight sentences, front-loaded with the action, then the interaction outcome. No filler or repetition of the title or annotations.

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-param, zero-required, no-output-schema tool, it explains the call flow and the returned status/secret, which covers the biggest unknowns. It leaves gaps on how the access secret is subsequently used and on the undocumented 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 description coverage is only 43% (3 of 7 params), so the description is expected to compensate, but it only gestures at the free-text store description. country, website, vertical, and company_name receive no meaning, format, or optionality guidance in either place.

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 (start a merchant/advertiser onboarding application) and immediately describes the interaction model (automated evaluator responds with question/approval/decline). This clearly distinguishes it from the read/discovery siblings like list_programs and get_product_feed.

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: use this to begin onboarding a new merchant and to drive the interview via free-text. There is no explicit when-not guidance, no mention of what to do for an existing in-progress application, and no routing away from alternatives such as request_tracked_links.

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

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

Annotations declare openWorldHint=true, idempotentHint=false and destructiveHint=false, and the description adds real context on top: the affiliate is provisional, the account is claimed and payout details added later via update_profile, and email is not required. It stops short of saying whether repeated calls create multiple provisional affiliates or what the returned link set looks like, but the workflow disclosure is strong.

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 sentences with no waste; the eligibility condition is front-loaded, the mutation/claim workflow follows, and the sibling routing closes it out. Every clause earns its place.

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

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

For a non-idempotent mutation tool with 12 largely undocumented parameters and no output schema, the description covers the workflow and alternatives well but leaves the input surface underspecified. An agent still lacks guidance on what the filter parameters do or how to shape a request.

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 only 42% across 12 parameters, so the description carries a heavy burden and mostly doesn't meet it. It clarifies only claim_email ('Email is optional'), while topic, channel, country, category, traffic_daily, traffic_monthly and limit are unexplained in both places.

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

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

The description states a specific verb+resource (creates a provisional affiliate and returns tracked links) and scopes it precisely to callers without an account. It distinguishes this from create_tracking_links and get_monetization_feed by name, so an agent can route correctly without opening a schema.

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

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

Explicit when-to-use ('when you have no Clickwise account yet'), plus named alternatives with the condition that selects each: use create_tracking_links with an API key, use get_monetization_feed for ready-made cards and an embed. This is textbook when/when-not/alternatives routing.

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

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

Adds substantial context beyond annotations: auth requirements (X-API-Key or Bearer), the sandbox key behavior (returns example links that never earn), the freshness/permissions/caps caveat, and crucially the side effect that a Clickwise /dl/ tracked link is created the first time a product is returned — which explains why readOnlyHint is false. Ceiling of behavioral disclosure for a search 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?

Information-dense with little wasted wording, but delivered as a single run-on paragraph mixing auth, return fields, and query modes, so nothing is visually front-loaded beyond the opening clause. Functional but not well structured.

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, and the description compensates by enumerating the returned product fields (id, gtin, title, price, currency, url, image, merchant, availability, country, brand, category, regular_price, description, size, color, group_id) plus count/total/total_exact. An agent has enough to call and interpret 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 only 30%, so the description carries the burden and largely does: it defines min_price/max_price semantics (inclusive, in each product's own currency, no conversion), currency filtering, offset pagination, and the roles of text/brand/category/country/gtin. It omits the limit default/max behavior, leaving that one parameter to the schema alone.

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

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

States a specific verb+resource ('Search fresh GTIN products in the catalog your affiliate can deliver') and scopes it with a real constraint, distinguishing it from siblings like get_product_feed and get_catalog_stats without opening their schemas.

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

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

Explains the query modes clearly ('Search by text, brand or category, or list one market by country alone') and the gtin case ('every market carrying that GTIN is searched'), giving the agent concrete selection criteria among parameters. It stops short of naming when to prefer a sibling tool such as get_product_feed over this search.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the crucial mechanism: 'Overwrites the fields provided.' That tells the agent unmentioned fields are preserved and supplied fields are clobbered, which the annotations alone do not convey. It could go further on reversibility or whether payment_method changes have 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 tight sentences, front-loaded with the verb and resource, then prerequisites, then the overwrite semantics. No filler and nothing redundant.

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

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

Covers purpose, credentials, and overwrite behavior for a 7-parameter mutation tool with no output schema. Remaining gaps are minor: no mention of error/permission behavior or response shape, though the latter is less critical here.

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

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

Schema description coverage is 14%, so the description must carry the weight, and it names all five mutable fields plus the two credential parameters already required. The main gap is that only payment_method has a schema-level example object, while formats for website_url and claim_email are left implicit.

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 (update a creator's monetization profile) and enumerates exactly which fields can be changed (claim email, display name, website, country, payment method). No sibling tool updates profiles, so it is clearly distinguishable from request_tracked_links, get_payment_status, etc.

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

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

Explains the prerequisite credential source (application_id + access_secret from request_tracked_links) and the use case (assistant completing claim/payout details without leaving chat). It stops short of stating when NOT to use it, e.g. pointing to request_tracked_links for initial setup vs. this tool for later edits.

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