Affilio Link Tools

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

No annotations are present, so the description carries the full behavioral burden. It does disclose the consequence of the call (link appears in storefront listings, trackable per-product), which is useful, but says nothing about idempotency, whether re-linking the same pair duplicates, ownership/permission requirements, or what happens if the link is already associated elsewhere.

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 core action and followed by the effect and the multiplicity rule. No filler and nothing redundant with the schema.

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?

An output schema exists, so return values needn't be explained, and the parameter side is fully covered. However, for an unannotated mutation tool the description leaves meaningful gaps around permissions, overwrite/duplicate behavior, and failure modes, which is only borderline complete.

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

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

Schema coverage is 100% and both IDs are explained there, so baseline is 3. The description adds genuine semantic value beyond the schema by stating the multiplicity model — a product can hold multiple links, one per country, platform, or affiliate network — which tells the agent this is a many-to-many association rather than a replacement.

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+resource pair ("Associate an affiliate link with a product") and scopes it to the Affilio catalog, which clearly distinguishes it from create_link or update_link. It stops short of naming a sibling it is not, 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?

It supplies clear situational context: this is how you make an affiliate URL appear in storefront listings and be tracked per-product. There is no explicit "when not to use" or routing to alternatives such as auth.create_link, but the usage trigger 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?

With no annotations, the description carries the full burden and succeeds. It discloses that archiving is a soft-delete, that archived links stop redirecting, that records and analytics are preserved, that Bearer token authentication is required, and that failures return an auth_error envelope. This covers the operation's side effects, security requirements, and error 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?

The description is tightly organized: an action statement, two bullet-like behavioral consequences, a usage recommendation, auth/error notes, and a reference link. Each sentence earns its place, and the most decision-relevant information is front-loaded.

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 tool with an output schema, the description covers everything needed to invoke it correctly: action, effect, when to use, authentication requirement, error envelope, and a technical reference. Nothing essential is missing.

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

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

The schema description for link_id already provides 100% coverage, identifying it as a Link ID and noting that archived links preserve history. The tool description reinforces this by explaining the soft-delete semantics and preservation of analytics, adding behavioral context beyond the schema's bare parameter definition.

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 opens with 'Archive (soft-delete) an affiliate link,' using a specific verb and resource while immediately clarifying the operation type. It distinguishes itself from hard deletion and from siblings like auth.update_link and auth.set_link_visibility by explaining that archived links are hidden from default list views and stop redirecting.

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 provides clear guidance: 'Use this instead of hard deletion to maintain historical data' and explains the behavioral consequences (hidden from lists, stops redirecting, preserves click history/analytics). It lacks an explicit comparison to flood of sibling alternatives such as set_link_visibility or update_link, but the context is sufficient to know when archiving is appropriate.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses Bearer-token authentication, the permanent/non-expiring nature of the link, account ownership with dashboard analytics, automatic URL validation and network classification, QR generation, and the `auth_error` envelope on auth failure. This goes far beyond the bare 'Create a new affiliate link' that a weaker definition would stop at.

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

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

The description is longer than minimum length but well-organized, with each paragraph earning its place: purpose, sibling differentiation, automatic behaviors, response contents, auth, and reference. The 'IMPORTANT' callout front-loads the key distinction from `shorten_url`, though the trailing blog reference 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 one-parameter tool with an output schema and zero annotations, nothing an agent needs to call it correctly is missing: usage conditions, authentication mechanism, failure envelope, response summary, and a technical reference. The output schema already documents return values, so the description's response overview is a bonus rather than a required burden.

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% — the schema already documents the single `url` parameter, valid HTTP/HTTPS inputs, and network auto-detection. The description echoes this ('validates the target URL, auto-classifies its affiliate network') without adding new parameter-level meaning, so the baseline 3 is appropriate.

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

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

Opens with a specific verb+resource+scope: 'Create a new affiliate link in your Affilio account.' It explicitly distinguishes itself from the sibling `shorten_url` by emphasizing this is the AUTHENTICATED, PERMANENT, account-owned variant. An agent can tell these two tools apart 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?

Gives an explicit routing rule: 'Prefer this over the unauthenticated `shorten_url` whenever the user wants a long-lived, tracked link.' The conditions that select this tool (long-lived, tracked) are stated upfront, and the inverse condition that would select the alternative is 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?

With no annotations, the description carries the behavioral disclosure burden. It states this is a creation operation, that a Bearer token is required, and that the response contains the new product ID for downstream use. It also clarifies the product-to-affiliate-link relationship. It does not cover idempotency or error behavior, but it provides meaningful operational context beyond the bare 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?

The description is concise, front-loaded with the main action, and every sentence adds value: the action, the product concept, downstream usage of the returned ID, authentication, and a reference link. No filler or unnecessary 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?

The tool is simple enough, the input schema is fully documented, and an output schema exists, so the description does not need to explain return values in detail. It covers the domain model, the required auth, and the follow-up operations. It could be more explicit about when not to use it, but for a create-with-five-parameters tool it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents all five parameters with examples. The description adds conceptual context about products and affiliate links, but it does not add parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Create a new product in your Affilio product catalog.' It distinguishes products from links by explaining that products are promoted via affiliate links and can have multiple links, which separates create_product from sibling auth.create_link and auth.add_product_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 description gives clear context for when to call this tool: before adding product links or storefront operations, since 'the response includes the new product's ID' needed by auth.add_product_link and auth.get_product. It does not explicitly state when not to use it or name alternatives, but the product/link distinction makes the intended usage clear.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals that Bearer token authentication is required and that an auth_error envelope is returned on authentication failure or ownership mismatch. It does not explicitly state that the operation is non-mutating, but the 'Retrieve' and 'Returns' language plus the read-like tool name make that clear.

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

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

The description is compact and well-structured: a one-sentence purpose, a concise list of returned fields, an auth requirement, and an error behavior note. Every sentence earns its place, and the technical reference is non-intrusive.

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

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

Given a single required parameter, an existing output schema, and no annotations, the description is complete enough. It covers what the tool returns, how it authenticates, and how failures surface. An agent has enough information to select and invoke the tool 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 input schema has 100% coverage: link_id is described as the ID returned by auth.create_link or auth.list_links. The description adds no additional parameter format, constraints, or resolution details beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb-resource pair: 'Retrieve a single affiliate link by its ID.' It also enumerates the full metadata returned, which differentiates it from sibling tools like auth.list_links (listing) and auth.get_link_stats (stats-focused). The scope is singular and 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?

Provides clear context: use when you have a link_id and need the full metadata record for one link. It also specifies the authentication requirement and failure envelope. It does not explicitly name alternatives or say when NOT to use it, but the context is strong enough for an agent to select it appropriately.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explicitly states the Bearer token requirement and flags that data availability depends on analytics backend configuration, which is a meaningful limitation. It does not discuss rate limits or error behavior, but the get/retrieve semantics and output schema cover most remaining operational concerns.

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

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

The definition is compact: purpose, return composition with caveat, and auth requirement are stated in three substantive sentences followed by a short reference URL. It is front-loaded and free of filler, though the external reference line is optional.

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

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

For a one-parameter read-only analytics tool with an output schema, the description covers submission context (link_id), authentication, and the limits of data availability. It might be improved by stating behavior for invalid or zero-click links, but the output schema and existing caveat make it sufficiently complete for selection and 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?

The single parameter is fully documented in the input schema ('Link ID returned by auth.create_link or auth.list_links'), so schema coverage is 100%. The description only refers to 'a specific affiliate link' and adds no semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with the specific verb 'Retrieve' and the resource 'click analytics for a specific affiliate link,' then lists the aggregated traffic dimensions returned. It is clearly distinct from siblings like auth.get_link, which would return link record data rather than analytics, although it never names or contrasts those siblings explicitly.

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

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

The first sentence establishes the intended use: fetch click analytics for one link, and the 'specific' wording rules out bulk or comparative reporting. No alternative tool is named and no when-not-to-use conditions are given, so the guidance is clear context without exclusions.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the Bearer token authentication requirement and the read-only nature of retrieving a product, and it summarizes what metadata is returned. It does not describe edge cases like invalid IDs, but for a straightforward single-product getter this is a minor omission.

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

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

The description is four sentences with no filler. It front-loads the action and resource, then efficiently covers return contents, authentication, and a reference link. Every sentence serves a purpose.

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

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

For a one-parameter, single-product getter with an output schema available, the description is complete enough to call correctly. It includes the required parameter origin, what the response contains, and the authentication prerequisite. Nothing essential is missing.

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

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

Schema coverage is 100%, and the product_id parameter already has a clear description explaining it comes from auth.create_product or auth.search_products. The tool description adds only the context of retrieving by ID, so its parameter-level contribution beyond the schema is minimal but acceptable.

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 opens with a specific verb and resource: 'Retrieve a single product from your Affilio product catalog by ID.' This clearly distinguishes it from siblings such as auth.list_store_products and auth.search_products, which operate over multiple products or use search criteria.

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

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

The tool says it retrieves a single product by ID, which clearly implies it is for when you already have a product_id. The parameter description adds that product_id comes from auth.create_product or auth.search_products, giving useful context. It does not explicitly name alternatives or when-not-to-use cases, but the intended usage is clear.

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

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

With no annotations provided, the description carries the full burden of disclosure. It explicitly states 'Retrieve' (a read operation), describes the full contents of the response, and calls out the Bearer token authentication requirement. It does not discuss deeper behavioral traits like rate limits or error semantics, but for a simple parameterless getter this is solid coverage.

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

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

The description is compact and well-organized: a one-line purpose, a bullet-style list of returned fields, an authentication note, and a reference link. Every sentence earns its place, and the core retrieval intent is front-loaded.

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 read tool with an output schema available, the description is fully sufficient. It names the resource, details the return contents, and states the authentication requirement. Nothing needed to invoke the tool correctly is missing.

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

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

The tool has zero parameters and the schema has 100% description coverage, so there is nothing for the description to add regarding parameter meaning. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on the return payload instead.

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 opens with a specific verb and resource: 'Retrieve your Affilio storefront configuration.' It lists the exact fields returned, distinguishing it clearly from sibling tools like auth.get_product or auth.list_links. An agent can immediately tell this is the read-only storefront-level getter.

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 makes clear it returns store configuration and requires Bearer token authentication, giving a usable context. However, it does not explicitly state when to use this tool versus alternatives such as auth.update_store or when a cached value might suffice. No exclusions or alternative routing are provided.

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

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

With no annotations, the description carries the burden of disclosure. It states the operation is a list (read-only), enumerates returned content ('status, configuration, and credential metadata'), and mentions Bearer token authentication. It does not discuss rate limits, pagination, or error behavior, but those are less critical for a parameterless read-only call.

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 substantive sentences plus a reference link. The purpose is front-loaded, the return contents are in the second sentence, and the dependency on auth.search_products is a high-value note. 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 no-argument list tool, this is complete: purpose, returned data categories, the related search tool's prerequisite, and authentication requirement are all present. An output schema exists, so the description need not spell out return value 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?

The input schema has zero parameters, so the 0-parameters baseline of 4 applies. The description adds no parameter-level details because there are none to document.

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 opens with a specific verb and resource: 'List all affiliate platform integrations connected to your Affilio account.' The resource is distinct from sibling list tools (links, products, stores), though it never names a sibling or explicitly contrasts with auth.list_links or auth.list_store_products.

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 useful context by stating that 'Active integrations are required to use auth.search_products for live product search,' which implies checking this tool before searching. It lacks explicit when-not-to-use guidance or alternatives, so it stops short of a 5.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states the Bearer token authentication requirement, return order (newest first), and pagination behavior. It implies a read-only operation though not explicitly stated, and doesn't mention rate limits or potential errors, but covers the essential behavioral traits.

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?

Five clear sentences, front-loaded with the purpose, then return details, pagination guidance, and auth requirement. No redundancy, and 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?

Given the low complexity, presence of an output schema, and full param schema, the description covers purpose, return summary, auth, and pagination. It lacks explicit alternatives but includes a technical reference link, making it complete enough for confident usage.

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 schema already fully describes both skip and limit parameters (100% coverage). The description adds only a pagination usage hint without new semantic details, so it meets the baseline for a well-covered schema without adding extra meaning.

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 clearly states the verb 'list', the resource 'affiliate links', and scope 'in your Affilio account'. It also mentions pagination, which distinguishes it from single-link retrieval tools like auth.get_link and ranked list auth.list_links_ranked.

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 advises using skip and limit for pagination in large collections, giving explicit usage context. However, it doesn't explicitly contrast with sibling tools like list_links_ranked, so it's clear but not fully differentiated in terms of when-not-to-use.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It clearly discloses the ordering behavior, pagination via skip/limit, and the authentication requirement. It does not explicitly state that this is a read-only operation or mention rate limits, but the behavioral traits most relevant for invoking it are present.

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

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

The description is concise and front-loaded with the primary purpose and ordering behavior. The use-case sentence and technical reference are useful but not strictly necessary, making it slightly longer than the minimum. Still, every sentence contributes meaning and there is no fluff.

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

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

Given only two simple optional parameters and an output schema, the description is complete. It covers what the tool returns, how results are ordered, how to paginate, why it is useful, and what authentication is required. An agent has enough information to invoke it correctly without inspecting additional metadata.

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 skip and limit are already fully documented with defaults and constraints. The description adds value by explicitly tying the two parameters together as the pagination mechanism and clarifying the ordering context in which pagination applies. This goes slightly beyond simply restating 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 clearly states the tool lists affiliate links and explicitly defines the ranking behavior: highest click count first. It also differentiates itself from auth.list_links by noting it returns the same schema but ordered by total clicks descending. This makes it easy for an agent to distinguish from sibling tools.

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 concrete use cases: identifying top performers, optimizing content strategy, and spotting underperforming links. It also references auth.list_links as the base schema, implying the difference between the two. It stops short of explicitly stating when NOT to use this tool, but the ranking context is clear enough.

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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It discloses the response contents, pagination behavior, storefront ordering, and Bearer token requirement. For a read-only list operation, this is reasonably transparent, though it does not mention rate limits or explicit read-only guarantees.

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

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

The description is concise and front-loaded with the main purpose. Each sentence adds useful context such as return fields, ordering, pagination, authentication, and a reference link. The technical reference link is slightly extraneous but not distracting.

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

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

Given the tool's low complexity, an output schema, and fully described optional parameters, the description covers the essentials: what is returned, pagination, ordering, and authentication. It does not explicitly route agents away from sibling tools or state read-only behavior, but for a list endpoint these omissions are minor.

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 both skip and limit already have clear descriptions, defaults, and bounds. The description only reinforces pagination without adding semantic details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List all products assigned to your Affilio storefront.' It clearly conveys the scope and distinguishes this from a generic list call, though it does not explicitly contrast it with sibling tools like auth.search_products or auth.get_product.

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 concrete operational guidance ('Use skip + limit to paginate through large storefronts') and mentions authentication. However, it does not explain when to prefer this tool over sibling alternatives such as auth.search_products or auth.list_links, leaving some selection burden on 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?

With no annotations, the description must carry the behavioral burden; it usefully enumerates the returned fields (name, price, image URL, affiliate link, ASIN, metadata), aiding the agent. But it omits rate limits, failure modes, and explicitly stating this is a non-mutating read—search implies read but is never asserted, and the platform-connection prerequisite only appears in the schema.

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

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

Two compact sentences, front-loaded with the purpose and then the return shape and workflow handoff. Every sentence carries distinct value with no redundancy.

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

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

Given a 3-param tool with full schema coverage and an output schema, the description covers purpose, return contents, and downstream usage adequately. The only notable gap is the platform-integration prerequisite, which lives in the schema rather than the description.

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

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

Schema description coverage is 100%, so the schema fully documents query, platform (with supported values), and limit. The description adds no parameter-level meaning beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb (Search) and resource (products) scoped to 'a connected affiliate platform', and clarifies it returns live catalog data rather than stored records, which implicitly separates it from siblings like get_product or list_store_products. It does not explicitly name any sibling, 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 line 'Results are ready to pass directly to auth.create_product' gives a clear workflow context (find then create), which tells the agent when to reach for this tool. However, there are no exclusions or explicit alternatives (e.g., when to use list_store_products instead), so it stops short of full routing guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the visible effect on the storefront, the product scoping, and the auth requirement. However, it does not mention whether the operation is reversible, whether setting a link private removes an existing storefront display immediately, or what relevant state changes occur on the server. For a mutation tool with zero annotation coverage, this is adequate but not thorough.

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

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

The description is broken into short, readable paragraphs with the main action front-loaded and supporting context (scoping, auth) following in order of importance. The only extraneous element is the trailing technical-reference URL, which adds little for tool-selection and slightly dilutes the focus, but overall the text is efficient and 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?

For a moderate-complexity mutation with an output schema and fully-documented parameters, the description is fairly complete: it covers purpose, scoping, and authentication. Minor gaps remain — it does not address idempotency (setting visibility to its current value) or the immediacy of the storefront update — but the presence of an output schema relieves the need to explain return values, so nothing essential to 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%, so the schema already documents all three parameters well, giving a baseline of 3. The description adds genuine meaning on top by explaining the real-world consequence of the visibility values ('Public links appear in the product's Affilio storefront listing; private links are hidden'), which enriches the visibility parameter's semantics beyond the schema's value definitions.

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 opens with a specific verb-plus-resource ('Set the public/private visibility of an affiliate link within a product') and immediately clarifies the practical effect: public links appear in the storefront listing, private links are hidden. This distinguishes it from the sibling auth.update_link, which would presumably handle broader attribute changes, so an agent can clearly differentiate this tool's focused scope.

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

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

The description states the scoping constraint ('Visibility is scoped to the product the link belongs to') and the authentication prerequisite (Bearer token), but it gives no when-to-use vs when-not-to-use guidance and names no alternatives. An agent is left to infer when this tool is preferable to auth.update_link or auth.archive_link, so selection guidance is essentially absent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses partial-update semantics, full replacement of labels, the return value ('Returns the updated link object on success'), and authentication requirements ('Requires Bearer token authentication'). This is strong transparency for a 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?

The description is compact and front-loaded with the action and resource. Every sentence earns its place: partial-update semantics, label replacement, return value, auth, and a reference link. No filler or redundant restatement of the tool name.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers the critical invocation details: partial updates, label replacement, auth, and success return. It is slightly incomplete in that it does not guide the agent toward sibling update-like tools (e.g., set_link_visibility), but nothing needed to call this specific tool correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents that omitted fields are unchanged and labels replace existing values. The description adds global partial-update framing and the return behavior, but does not substantially add parameter-level meaning beyond the schema, so it stays at the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Update an existing affiliate link's title, destination URL, or labels.' It clearly identifies the scope of the operation. It does not explicitly differentiate from sibling tools like auth.set_link_visibility or auth.archive_link, but the field list makes the purpose unambiguous.

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

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

The description gives clear context: 'Fields omitted from the call are left unchanged (partial update)' and 'Labels are replaced entirely — pass the full desired label set, not a delta.' This tells the agent how to call it correctly. It does not explicitly state when to prefer a sibling tool, so it misses the exclusion/alternative guidance needed for a 5.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose Bearer token authentication and the partial-update contract ('fields omitted are left unchanged'), which is valuable. It says nothing about reversibility, error behavior, or whether the name is unique/validated, leaving real gaps for a 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?

Front-loads the purpose, then the partial-update rule, then the out-of-scope routing, then auth. Efficient overall, though the marketing 'Technical reference' blog URL adds little for an agent deciding how to call the tool.

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

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

An output schema exists, so return values need not be explained, and the description covers scope, partial-update semantics, auth, and the out-of-scope branding case. Only error/validation behavior is unaddressed, which is a minor gap for a low-complexity 3-param update.

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 per-parameter descriptions including the accepted layout values, so the schema already does the heavy lifting. The description's only added value is the 'any combination / omitted means unchanged' framing, which is a baseline-3 contribution.

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 your Affilio storefront's metadata') and enumerates exactly which fields are in scope, which lets an agent distinguish it from auth.get_store and the product/link tools. It does not name a sibling explicitly, so it stops 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?

Gives clear context for use ('provide any combination of name, description, layout') and an explicit when-not: full branding updates must go through the Affilio dashboard → Storefront settings. No alternative MCP tool is named, but the exclusion is concrete and actionable.

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?

No annotations are provided, so the description carries the full burden. It does well: it discloses the multi-region testing behavior, the shape of the result (per-region resolved domains plus a redirect-detected summary), and honestly flags that the test has limitations. It stops short of naming those caveats, timeouts, or rate limits, so an agent can't predict cost or failure modes.

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 core action and mechanism, followed by a return-value sentence and a bulleted usage list. Slightly longer than needed given the schema covers input validation, but every line adds orientation.

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?

An output schema exists, so return-value detail is not required, and the description still summarizes it usefully. The main residual gap is the unnamed 'caveats about the test's limitations' and any latency or regional-coverage boundary, minor for a single-parameter read-style check.

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

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

Schema description coverage is 100% and the schema itself defines the accepted URL forms (amazon.<tld>/dp/, /gp/product/, amzn.to) and rejection of non-Amazon URLs with an example. The description adds no parameter detail beyond that, so baseline 3 applies.

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

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

The description gives a specific verb (test) and resource (an Amazon affiliate link across US/EU/Asia vantage points) and names the concrete mechanism being verified: OneLink geo-redirect. It is clearly distinguishable from siblings like check_url (generic URL liveness) and get_link_stats (performance data).

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

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

It provides an explicit 'Use this tool when the user needs to' list with three concrete scenarios (international redirect check, OneLink verification, diagnosing missed international commissions). Implicitly excludes generic link validation, which routes to check_url.

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?

No annotations exist, so the description carries the full disclosure burden; it does state the key behaviors (follows redirect chains, extracts titles, special-cases Amazon/AliExpress availability), which is genuinely beyond the schema. However it says nothing about timeouts, non-HTML/JS-rendered pages, bot-blocked responses, rate limits, or what a failure looks like — meaningful gaps for a network-fetching 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?

The one-line purpose statement is front-loaded and the bulleted trigger list is scannable. There is mild redundancy between the paragraph describing outputs and the bullets restating the same use cases, but nothing is 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?

With an output schema present, the description need not explain return shape, and a single fully-documented parameter keeps the surface small. What is missing is failure-mode context (broken DNS, timeouts, blocked pages) that an agent would want before deciding to rely on 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 coverage is 100% and the single `url` parameter is already documented in detail (with an example), so the baseline applies. The description restates the same behavior but adds no per-parameter meaning such as accepted formats, whether tracking params are stripped, or handling of non-HTTP schemes.

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 opening line names a specific verb and resource ('check the health and destination of a URL') and adds a clarifying gloss ('link checker / redirect resolver'), then enumerates the concrete outputs: final resolved URL, status codes, page title, and Amazon/AliExpress availability. It never names the most confusable sibling (check_international_redirect) or contrasts with shorten_url, 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?

A dedicated 'Use this tool when the user needs to:' block gives four concrete trigger scenarios (verify affiliate link not dead, resolve short link destination, check product availability, inspect redirect chain). That is clear positive guidance, but there are no exclusions and no pointer to an alternative tool for related-but-different jobs.

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

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

With no annotations, the description does carry useful behavioral weight: it discloses the base64-PNG return format and the embed pattern. However, it says nothing about authentication, rate limits, failure modes for invalid URLs, or image dimensions, so the safety/operational profile is only partially covered.

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

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

The first sentence front-loads the core action and output, followed by return-format details and a scannable bullet list. The bullets are slightly redundant with the opening sentence but remain useful and short; no filler paragraphs.

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?

An output schema exists, so return values need no exposition, and the schema fully documents the five parameters. The description is complete for invocation purposes, with only tangential gaps (auth, limits, image size) remaining.

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

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

Schema description coverage is 100% and each parameter has an example, default, and interaction note (transparent overrides background_color). The description only restates the categories as "color, transparency, and dot style" without adding syntax, constraints, or edge-case guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Generate) and resource (a branded QR code PNG for a URL) with the output format named up front. It is clearly distinguishable from siblings like shorten_url or check_url, since none of them produce an image artifact.

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

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

Provides four explicit use-case bullets (scannable QR, print-ready marketing, email/web embedding, branded visual identity), giving a clear picture of when to reach for it. It stops short of saying when NOT to use it or pointing to an alternative, so it lands just below the top score.

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?

No annotations exist, so the description carries the full burden and largely does: 30-day expiry, not tied to any account, unauthenticated access, security verification with pending=True on new/unknown domains, and URL-level deduplication returning the same code. These are exactly the behavioral traits an agent needs before calling a URL shortener.

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 correctly: the unauthenticated/temporary warning and the auth.create_link escape hatch come before any detail. Slightly long, and the 'Use this tool when' bullet list partly restates the earlier prose, costing some economy without hurting comprehension.

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?

Complete for a one-parameter tool with an output schema present. Lifetime, ownership, verification state, dedup behavior, and the QR side-effect are all disclosed, so nothing an agent needs to call it correctly or set user expectations is missing.

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

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

Only one parameter, and the schema already documents it fully (100% coverage, accepted URL form, affiliate networks, example). The description adds meaning beyond the schema by explaining that identical URLs deduplicate to the same short link and that a branded QR is generated in the same call, which affects how the agent should interpret and reuse results.

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 (shorten URL into an Affilio.link short link) and immediately scopes it as the unauthenticated, temporary, MCP-hosted variant at mcp.affilio.link/r/{code}. That naming of the counterpart (affilio.link/ur/{code} via auth.create_link) makes it distinguishable from siblings 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?

Explicitly states when to use this tool (social sharing, QR for print, throwaway links) and names the alternative plus its selection condition: permanent, account-owned, analytics-bearing links require auth.create_link with a bearer token. Both the when and the when-not are present.

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