Affilio Link Tools

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 does useful work by stating Bearer token authentication is required, noting the auth_error envelope on failure, and explaining that a product can have multiple links across country/platform/network. It could go further on idempotency or duplicate-link behavior, but the key operational traits are disclosed.

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

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

The description is well-structured and front-loaded: purpose, key constraint, workflow, auth requirement, error behavior. Every section earns its place and the numbered workflow makes the invocation sequence easy for an agent to follow without excess verbosity.

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 two-parameter mutation with an output schema already present, the description covers the essential context: why to use it, what the preconditions are, how to get the IDs, what auth is needed, and what happens on auth failure. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already has 100% coverage with clear parameter descriptions, so the baseline is 3. The description adds real value by showing the exact provenance of both parameters (link_id from auth.create_link, product_id from auth.create_product or auth.get_product) and embedding them in a runnable workflow with placeholder syntax.

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: 'Associate an affiliate link with a product in your Affilio catalog.' It clearly distinguishes this from related tools like auth.create_link and auth.create_product by framing it as the connection step in the workflow, not the creation of either entity.

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 'Typical workflow' section gives concrete steps and explicit ordering: create_link first, create_product second, then add_product_link with the returned IDs. This gives clear context for when to use it, though it does not explicitly mention when not to use it or name alternative tools for exclusion.

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 full burden and does well: it states the return type (array), sort order, which fields are included, pagination behavior, and Bearer token authentication. It does not cover failure modes or rate limits, but the disclosed behavior is substantially beyond the bare tool name.

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

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

The description is compact and well structured: purpose, return details, pagination usage, and authentication are each covered in separate concise sentences. The technical reference link is the only nonessential element, but it does not bloat the text.

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 paginated list tool with two optional parameters and an output schema, the description is complete: it explains what the tool lists, how results are ordered, what each item includes, how to paginate, and the auth requirement. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and both parameters already have clear descriptions and bounds. The description adds a small but useful semantic layer by explicitly connecting skip and limit to paginating through large link collections, reinforcing the intended usage 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 opens with a specific verb and resource ('List affiliate links in your Affilio account') and clarifies it returns paginated results sorted by creation date, newest first. This distinguishes it from the sibling list_links_ranked by noting the sort order, and from get_link by indicating it lists many items.

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 clearly instructs to use skip + limit for pagination, which is direct usage guidance for this tool. The when-to-use is implied by the list-focused purpose, but it does not explicitly contrast this with siblings such as list_links_ranked or get_link, so one minor exclusion is missing.

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 provided, the description carries the full burden. It discloses that results are live, requires Bearer token authentication, lists prerequisites, and enumerates relevant error envelopes such as plan_restriction and no_integrations_connected. It stops short of explicitly stating read-only semantics, but 'search' and 'returns listings' strongly imply no 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 well structured: a one-sentence purpose, a concise returns summary, prerequisites, and error envelopes. It is slightly longer than strictly necessary due to the technical reference link and repeated platform examples, but the organization helps an agent parse requirements 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?

For a search tool with an output schema and richly described parameters, the description covers the necessary context: prerequisites, authentication, error behavior, and the downstream use of results. It does not mention rate limits or explicit read-only guarantees, but these are not blocking for an agent to 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 already documents all three parameters with 100% coverage, including defaults, limits, supported values, and examples. The description adds no significant parameter-level meaning beyond what the schema provides, such as how limit interacts with pagination or how platform values map to integrations.

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: 'Search for products on a connected affiliate platform' and clarifies it returns live catalog listings with product details. The description differentiates from nearby tools like list_store_products by emphasizing the live external platform catalog and integration prerequisite, though it does not explicitly name sibling alternatives.

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 usage context: requires an active platform integration, advises verifying with auth.list_integrations, and notes results are ready for auth.create_product. It does not explicitly state when not to use the tool or name a specific alternative, but the integration prerequisite and 'live affiliate platform' framing make the intended scenario 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 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 provided, the description carries the full behavioral burden. It discloses that this is an update operation, clarifies partial-update behavior, and adds an authentication prerequisite: 'Requires Bearer token authentication.' It also scopes out full branding updates, which helps prevent misuse, though it does not discuss side effects 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?

The description is compact and front-loaded: purpose, partial-update semantics, scope boundary, auth requirement, and a docs link all appear in a short, readable block. The technical reference URL is slightly marginal for an agent-focused description, but the overall structure is efficient and every substantive sentence earns its place.

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

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

For a three-optional-parameter update tool, the description plus fully described input schema are nearly sufficient: it explains what can change, how partial updates work, what is out of scope, and what authentication is required. Since an output schema exists, the description does not need to document return values, though it could have mentioned what happens on success.

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 already documents all three parameters with 100% coverage, including accepted values for layout and individual 'omit to leave unchanged' notes. The description's 'fields omitted are left unchanged' line reinforces what the schema already says but does not add meaningful new parameter-level information.

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+resource: 'Update your Affilio storefront's metadata,' and then lists the exact modifiable fields (name, description, layout). This clearly separates it from sibling tools like auth.update_link and auth.get_store, so an agent can identify what this tool is for without guessing.

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 usage guidance: 'Provide any combination of name, description, and layout' and notes that omitted fields are left unchanged, implying partial-update semantics. It also gives an explicit when-not: full branding updates should go through the Affilio dashboard rather than this tool, though it does not explicitly name a sibling MCP alternative.

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 transparency burden. It discloses per-region results, the redirect_detected summary, and that caveats are always present, including continent-level vantage-point limitations. This is substantial, though it does not mention authorization requirements or network-side effects beyond the inferred remote test.

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 front-loaded with the core behavior, followed by bulleted use cases and a compact return summary. Structure is clean and each section earns its place; the closing 'Powered by Affilio.link' tagline is the only non-essential addition.

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 a complete input schema and an output schema, the description need not restate return values. It adds the missing context: when to use it, what the test checks, and its limitations. A minor gap is the absence of any explicit relationship or distinction from the sibling check_url tool.

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

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

The input schema already documents the single url parameter with 100% coverage, including accepted URL formats and a concrete example. The description adds no further parameter-level detail, which is acceptable given the schema coverage baseline.

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

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

The description opens with a specific verb ('Test'), a specific resource ('Amazon affiliate link'), and the precise behavior ('from US, EU, and Asia vantage points to check whether Amazon's OneLink geo-redirect is active'). This clearly differentiates it from sibling tools like check_url and shorten_url because the geo-redirect and vantage-point angle is explicit.

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

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

The description provides three explicit 'Use this tool when...' scenarios, allowing an agent to match user intent confidently. It does not name when-not-to-use alternatives or explicitly compare against the similar-sounding check_url, so it falls just 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It transparently explains that the tool follows redirect chains, returns HTTP status codes, extracts page titles, and detects availability only for Amazon/AliExpress product pages. This goes well beyond the input schema, though it does not mention potential external network behavior or side effects.

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

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

The description is well organized with a clear summary, a use-case bullet list, and a return-value block. It is slightly verbose because the return fields are also present in the output schema, but the structure makes the information easy to scan and act on.

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 is complete: it explains the tool's purpose, what it follows and returns, when to use it, and the special availability behavior for Amazon/AliExpress. Nothing essential for invoking or interpreting the tool 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 single parameter is already well documented in the schema. The description adds behavioral context but no additional parameter-specific semantics 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?

States a specific verb and resource: 'Check the health and destination of a URL (link checker / redirect resolver).' It clearly names what the tool does and distinguishes it from sibling tools like shorten_url, generate_qr, and check_international_redirect by focusing on health checking and redirect resolution.

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 an explicit bulleted list of when to use the tool: verifying affiliate/product links, resolving short links, checking Amazon/AliExpress availability, and inspecting redirect chains. It does not explicitly name alternatives or when-not-to-use conditions, but the use cases are clear enough for an agent to select it correctly.

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

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

Annotations are absent, so the description carries the transparency burden. It discloses the output format (base64 PNG), embeddability, configurable color/transparency/dot style, and the exact returned fields. This gives an agent a solid behavioral model for a non-destructive generation 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 well organized: a one-line summary, return format, use-case bullets, and a returns table. It front-loads the most important information and stays readable despite the promotional 'Powered by' line and documentation link.

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

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

The description covers the return contract, embedding usage, typical use cases, and customization capabilities. With only one required parameter and an output schema present, nothing critical is missing for an agent to call the tool correctly, though it could briefly mention URL validation constraints beyond the schema.

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

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

Schema description coverage is 100% and the input schema already documents every parameter with defaults and examples. The description only summarizes that 'color, transparency, and dot style are configurable,' adding no parameter detail beyond what the schema provides, so the baseline score 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 opens with a specific verb and resource: 'Generate a branded QR code PNG image for any URL with full visual customization.' It clearly distinguishes the tool from sibling link-management and URL-checking tools, and the title expands into a concrete capability an agent can act on.

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 includes a clear 'Use this tool when the user needs to' section listing four relevant scenarios, such as print-ready QR codes and embedding in email. It does not explicitly name alternatives or exclusion cases, but the sibling set contains no other QR-generation tool, so the context is strong.

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 does it thoroughly. It discloses the unauthenticated nature, 30-day expiry, security verification with pending state, deduplication behavior, and QR generation. It even explains what 'pending' means for redirects (202 until verified) and that expires_at is never null. No contradictions with 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?

The description is long but efficiently front-loaded: the primary purpose and critical caveats (unauthenticated, temporary, expiry) come first, followed by use cases and returns. The 'Returns' block is quite verbose and partly redundant given an output schema exists, but each element serves a purpose in clarifying unusual behaviors like pending and already_existed.

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 tool with no annotations, an output schema, and one simple parameter, the description covers all needed context: purpose, auth model, expiry, security, dedup, QR, use cases, and the sibling alternative. The docs link adds a final safety net. Nothing an agent needs to decide or call 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 coverage is 100% for the single 'url' parameter, which already includes format and example. The description adds value by explaining the URL is verified for security, unknown domains return pending, and identical URLs are deduplicated—semantics not in the schema. It enriches rather than repeats.

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 any URL into a compact, trackable Affilio.link short URL with affiliate link intelligence.' It explicitly distinguishes itself from auth.create_link and other siblings, noting this is the unauthenticated public shortener while permanent links belong to auth.create_link. The tool's scope is unambiguous.

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

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

Provides a dedicated 'Use this tool when the user needs to' section listing four concrete scenarios (social sharing, QR generation, compact links, throwaway links). Explicitly names the alternative: 'For a PERMANENT, account-owned link ... use the auth.create_link tool instead.' This is textbook 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.