Affilio Link Tools

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

With no annotations, the description carries the transparency burden. It discloses the Bearer token authentication requirement and the auth_error response envelope, adding behavioral context beyond the schema. It also explains the functional effect (storefront appearance, tracking) but doesn't cover edge cases like duplicate associations or invalid IDs. These details are useful enough for a 4.

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 purpose, then covers multi-link behavior, a numbered workflow, auth, and an error envelope in a logical order. It's appropriately sized with no redundant sentences; the technical reference link is the only extra, but it's harmless. Structure with the workflow list enhances scannability.

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 has only two parameters, both fully documented in the schema, and an output schema exists to cover return values. The description fills the remaining context: the exact workflow, authentication requirements, and failure mode. For a simple association operation, this is complete enough to select and invoke safely.

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 provides 100% coverage with descriptions for link_id and product_id. The description adds the workflow relationship, showing which prior tool returns each ID, and extends product_id sources to include auth.get_product. This adds meaningful context beyond the schema, so a 4 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 clear verb-object: 'Associate an affiliate link with a product in your Affilio catalog.' It distinguishes itself from sibling tools by detailing the connection purpose (storefront listings, per-product tracking) and the workflow context. This makes the tool's role 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?

It provides a typical workflow (create_link → create_product → add_product_link), which tells the agent when to use this tool as the final association step. It also notes that a product can have multiple links, implying this tool can be called repeatedly for different country/platform/network links. However, it doesn't explicitly state when not to use it or mention alternatives, so a 4 rather than 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 carries the full burden and does so excellently. It discloses the soft-delete behavior (hidden from default list views, stops redirecting), data preservation (click history and analytics intact), authentication requirements (Bearer token), and error response (auth_error envelope). This goes beyond a basic mutation description.

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 (around 80 words) and well-structured: a clear title line, a behavior block, a usage recommendation, and an auth note. Every sentence adds value; the technical reference link is informative without being filler. Front-loaded with the most important info.

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, the description covers all necessary context: what the tool does, when to use it, behavioral effects, and failure mode. The output schema handles return value specifics, so the description is complete without being redundant.

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 schema parameter description already explains that link_id is returned by auth.create_link or auth.list_links, and reiterates archival behavior. The tool description adds no new parameter-specific info beyond the schema, so it meets the baseline for high coverage.

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 'Archive (soft-delete)' and the resource 'affiliate link', making the purpose unambiguous. It distinguishes itself from a hypothetical hard-delete operation by explicitly saying 'Use this instead of hard deletion', and the effect (hidden, stops redirecting) is precise.

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 this instead of hard deletion to maintain historical data' gives an explicit when-to-use condition. It does not mention when not to use or alternative tools like set_link_visibility, but the guidance is sufficient for common use. Lacks explicit exclusions, so not a perfect 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 discloses critical behavioral traits: permanence, account ownership, non-expiry, URL validation, auto-classification, QR generation, Bearer token requirement, and error envelope. It fully covers the tool's side effects and prerequisites.

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 minimal but each sentence serves a purpose, leading with the core purpose and then important caveats. It could be slightly more compact, but the structure is logical and 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?

Given no annotations and an output schema present, the description compensates well by summarizing response contents and specifying authentication requirements. It also provides a technical reference link. The tool's complexity is sufficiently covered.

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 covers the `url` parameter (100%). The description adds value by noting accepted URL types (HTTP/HTTPS affiliate links) and auto-detection of the affiliate network, providing guidance 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 clearly states 'Create a new affiliate link in your Affilio account' – a specific verb and resource. It also explicitly distinguishes from `shorten_url` by emphasizing permanence and tracking, making its 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?

It provides explicit when-to-use guidance: 'Prefer this over the unauthenticated `shorten_url` whenever the user wants a long-lived, tracked link.' It also clarifies the authenticated context and the alternative, helping the agent choose correctly.

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

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

There are no annotations, so the description carries the full burden. It discloses the authentication requirement (Bearer token) and mentions the response includes the new product ID. However, it doesn't touch on error conditions, idempotency, or side effects beyond creation, leaving some behavioral gaps.

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: purpose, product context, response note, and auth requirement. It's efficient and front-loaded with the main purpose. The contextual sentences about product relationships are valuable but slightly verbose, costing a point.

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

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

The description is complete enough for a create tool. It explains the product's role, mentions the output schema (product ID) indirectly, and provides a technical reference link. The schema and output schema cover parameters and return values. Minor missing details about error handling or edge cases keep it from a 5.

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 provides 100% parameter coverage with detailed descriptions for all five parameters. The tool description itself adds no parameter-specific information beyond what's in the schema, so a 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 opens with a specific verb-resource pair: 'Create a new product in your Affilio product catalog.' It clearly differentiates from siblings like auth.create_link (which creates links) and auth.add_product_link (which adds a link to an existing product). The scope is well-defined.

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 usage context by explaining that the response includes a product ID needed for auth.add_product_link, auth.get_product, and storefront operations. This tells the agent when to use this tool (before adding links or storefront operations) but doesn't explicitly state alternatives or when not to use it, so a perfect score isn't warranted.

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 disclosing behavior. It clearly states that Bearer token authentication is required, that an auth_error envelope is returned on authentication/ownership failure, and that the link must belong to the authenticated account. Some additional details like rate limits are absent, but this is adequate for a simple retrieval 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-structured and front-loaded with the primary purpose, followed by return metadata and important context. The only minor issue is the trailing 'Technical reference' URL, which seems like a generic blog link rather than tool-specific guidance, adding slight noise.

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 low-complexity, single-parameter retrieval tool with an output schema present, the description is complete. It explains what the tool returns, the authentication requirement, error behavior, and ownership restrictions, leaving no significant gaps for the agent to guess.

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?

There is only one parameter, link_id, and the schema already provides a clear description of where the ID comes from. The tool description adds no additional parameter-level meaning beyond what the schema already covers, 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 'Retrieve a single affiliate link by its ID,' which clearly states the verb, resource, and scope. It distinguishes itself from sibling tools like auth.get_link_stats and auth.list_links by focusing on full metadata for a single 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 intended use is clear: you need a link_id, and the schema notes it comes from auth.create_link or auth.list_links. However, the description does not explicitly mention alternatives or when not to use it, so it lacks the full exclusionary guidance 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. It discloses the type of data returned (total clicks, unique visitors, geographic breakdown, referrers, device/browser), notes dependency on backend configuration, and explicitly states 'Requires Bearer token authentication' and provides a technical reference link. This provides substantial behavioral context beyond a bare 'get stats' statement.

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 well-structured: the first sentence states the core purpose, the second lists the data contents, and the third covers authentication and a technical reference. Every sentence contributes meaningful information, with no fluff 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 single-parameter tool with an output schema, the description is complete. It covers what the tool does, what data is returned, environmental dependencies, and authentication requirements. The external tech reference adds further context, and the output schema handles return structure, so no critical gaps are present.

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' is already explicit ('Link ID returned by auth.create_link or auth.list_links'), covering 100% of the parameter. The tool description adds only the context that the link is an 'affiliate link' but does not clarify parameter usage or formatting 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 clearly states 'Retrieve click analytics for a specific affiliate link,' combining a specific verb ('Retrieve') with a clear resource ('click analytics for a specific affiliate link'). This distinguishes it from sibling tools like 'auth.get_link' (which likely returns link details) and 'auth.list_links' (which lists links).

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

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

The description provides clear context that this tool is for obtaining traffic data for a link, implying its use when analytics are needed. It does not explicitly mention alternatives or exclusions, but the description's focus on 'click analytics' makes the usage scenario evident without ambiguity.

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. It discloses the Bearer token authentication requirement and lists the full product metadata returned. It does not cover error handling or rate limits, but for a simple get-by-ID read operation this is adequate.

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 purpose in the first sentence and return metadata in the second. The third sentence's technical reference URL is extraneous for an agent and adds minor noise.

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 get-by-ID tool, the description covers purpose, return payload, and auth requirement. The existence of an output schema reduces the burden of explaining return values. Minor gaps include no explicit error behavior and no mention of alternative tools.

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 provides a description for product_id (100% coverage), so the tool description adds little beyond restating that lookup is by ID. No additional syntax, format, or usage examples are given.

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 'Retrieve a single product from your Affilio product catalog by ID,' identifying the verb, resource, and scope. It distinguishes this from sibling tools like auth.list_store_products and auth.search_products by focusing on single-product retrieval.

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

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

Usage is implied through 'by ID' and the parameter description that product_id comes from auth.create_product or auth.search_products. However, it doesn't explicitly state when to prefer this over other getters or list/search tools, nor does it mention any 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 burden. It discloses an authentication requirement and enumerates the returned configuration fields. The verb 'Retrieve' implies a read-only operation, but it does not explicitly state that no modifications occur. Still, the behavior is transparent enough for a simple getter.

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 well-structured: one sentence for purpose, a clear list of returned fields, and a short auth note plus reference. Every sentence earns its place, and it's front-loaded with the primary action.

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 that the tool has no parameters and an output schema exists, the description goes beyond the minimum by listing the contained fields and the authentication requirement. It is complete for a simple store configuration retrieval 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 tool has zero parameters, and the input schema is empty. According to the rubric, a zero-parameter tool gets a baseline of 4. The description adds no parameter information, but none is needed.

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: 'Retrieve your Affilio storefront configuration.' This clearly distinguishes it from sibling tools like get_link or get_product, which target different resources. The 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?

The description implies when to use the tool: whenever you need the storefront configuration. It also provides a clear prerequisite (Bearer token authentication). However, it does not explicitly mention alternatives or exclusions, so it doesn't earn 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 carries the full burden. It discloses the read-only nature via the verb 'List', describes the output (status, configuration, credential metadata), and notes the authentication requirement. It does not mention pagination or side effects, but for a simple list tool this is sufficient. No contradiction with annotations (none).

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. The first sentence states the purpose, followed by output details, a usage dependency, authentication note, and a technical reference. Every sentence adds 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 the tool's simplicity (no parameters, has output schema), the description covers all relevant context: purpose, return contents, auth requirement, and relationship to auth.search_products. The output schema handles return value details, so the description is 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?

The tool has zero parameters, so schema coverage is trivially 100%. The rubric sets a baseline of 4 for zero-param tools, and the description adds no additional parameter information because none is needed.

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 all affiliate platform integrations for the Affilio account. The verb 'List' and specific resource 'affiliate platform integrations' distinguish it from sibling list tools (e.g., auth.list_links, auth.list_store_products). It also specifies the returned metadata (status, configuration, credentials).

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 explicitly ties usage to auth.search_products by stating active integrations are required for live product search. This gives a concrete 'when to use' scenario. It also notes the Bearer token authentication requirement, adding another usage prerequisite.

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 by disclosing the auth precondition, sort order, pagination mechanism, and the exact link fields returned. It omits potential error cases or rate-limit behavior, but the coverage is solid for a read-only list operation.

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

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

The description is well-structured and front-loaded: purpose in the first sentence, followed by return shape and pagination guidance. Every sentence earns its place; the technical reference link is optional but not padding.

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

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

For a simple paginated list tool with an output schema, the description covers the essential context: supported parameters, sort order, auth, and return fields. It does not mention how list_links differs from list_links_ranked, which would be valuable for tool selection, but overall 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%, with both skip and limit already containing defaults and constraints in the schema. The description only restates that skip+limit enable pagination, adding minimal semantic value over the structured 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 in the user's Affilio account with pagination. It specifies the sort order and returned fields, but it does not explicitly distinguish itself from sibling tool auth.list_links_ranked, leaving potential confusion about which to use.

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 guidance to use skip and limit for pagination through large collections, and notes the authentication requirement. However, it provides no when-not-to-use guidance or explicit comparison to alternative list tools.

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 behavioral disclosure. It discloses the ordering behavior, pagination via skip/limit, and the authentication requirement ('Requires Bearer token authentication'). It also clarifies that the output schema matches auth.list_links. It does not mention potential errors or rate limits, but for a read-only list tool this is adequate.

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 moderately sized and front-loaded with the core purpose in the first sentence. Each sentence adds relevant information (ordering, schema, use cases, pagination, auth, technical reference). The pagination sentence is slightly redundant with the schema, but overall it is well-structured and efficient.

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

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

For a simple two-parameter list tool with an output schema, the description is complete: it explains what it does, how it differs from auth.list_links, when to use it, how to paginate, and authentication requirements. It also points to the output schema, so no further return-value exposition is needed.

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% description coverage for both parameters (skip and limit), including defaults and ranges. The description only adds the generic phrase 'Use skip + limit to paginate', which reinforces the schema but does not provide additional semantic depth beyond what is already documented.

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 specifies the ranking criterion: 'ranked by click performance (highest click count first)'. It also distinguishes from the sibling auth.list_links by explicitly noting the ordering difference, making 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 provides practical use cases: 'identifying your top-performing affiliate links, optimising content strategy, and spotting underperforming links that need attention'. It also references auth.list_links as the base tool, implying when the ranked version is more appropriate, though it does not explicitly state when not to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that results are paginated, returns a specific set of fields, preserves storefront display order, and requires Bearer token authentication. It does not cover error cases or rate limits, but for a read-only list operation this is reasonably transparent.

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 well-structured: the opening sentence states the core purpose, followed by return content, ordering behavior, pagination guidance, auth requirement, and a reference link. Every sentence adds value and there is 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 that the tool has an output schema and a simple parameter set, the description fully covers what the tool does, what it returns, how pagination works, and authentication requirements. It even provides a technical reference. This is comprehensive enough for an agent 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 already fully documents both parameters (skip and limit) with descriptions, defaults, and bounds (100% coverage). The description adds a brief mention of pagination but no additional semantic meaning beyond what the schema provides, so a 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 clearly states the tool's purpose: 'List all products assigned to your Affilio storefront.' It uses a specific verb and resource, and the scope is distinct from search_products (which likely filters). However, it does not explicitly differentiate itself from sibling tools like auth.search_products or auth.get_product, so it falls short of a perfect 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 description implies usage by explaining pagination with 'skip' and 'limit' and notes it's for 'large storefronts,' but it does not specify when to prefer this over auth.search_products or auth.get_product. There are no exclusions or alternative recommendations, leaving usage context incomplete.

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 discloses authentication requirements, error envelopes with specific meanings, prerequisites, and integration dependencies. The read-only nature is implied by 'Search' and 'Returns live product listings', and no contradictions exist.

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

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

The description is well-structured with a clear opening, prerequisites, error envelopes, and authentication note. It is slightly longer than necessary, repeating the Bearer token requirement in both the auth_error description and the standalone line, but overall each section 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 tool's moderate complexity, an existing output schema, and no annotations, the description is remarkably complete. It covers prerequisites, integration verification, exact error scenarios, authentication, and even includes a technical reference link. No significant gaps remain.

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

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

The input schema already documents all three parameters clearly with descriptions, defaults, and constraints (100% coverage). The description adds some recurring context about platform integration and error cases, but it does not materially enrich the meaning of individual parameters beyond what the schema provides, 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?

The description clearly states the tool 'Search for products on a connected affiliate platform' with a specific verb and resource. It also distinguishes itself by describing live listings, direct affiliate links, and integration with auth.create_product, which separates it from sibling list/create 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 provides strong contextual guidance: prerequisites for active integrations, verification via auth.list_integrations, and when errors may surface (e.g., plan_restriction). It does not explicitly state when *not* to use this tool or mention alternative search/list tools, so it stops short of a full 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?

Despite having no annotations, the description discloses key behavioral traits: public links appear in storefront listings, private links are hidden, visibility is scoped to the owning product, and Bearer token authentication is required. It does not cover reversibility or direct-URL accessibility, but it provides meaningful safety and effect context.

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

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

The description is front-loaded with the purpose, followed by concise effect and auth statements. The technical reference URL is somewhat generic and does not add tool-specific value, which prevents a perfect score, but overall the structure is clear and compact.

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

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

With a simple three-parameter schema and an output schema present, the description sufficiently covers the tool's purpose, effect, scope, and authentication. It does not detail error cases or permissions beyond Bearer auth, but these are not critical for selecting and invoking this straightforward visibility mutation.

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 provides 100% coverage for all three parameters with detailed descriptions. The tool description adds only the product-scoping nuance and does not offer additional parameter semantics 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 'Set the public/private visibility of an affiliate link within a product,' a specific verb plus resource and clear scope. It distinguishes this tool from siblings like update_link, archive_link, and create_link by focusing solely on visibility.

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

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

The description explains when to use this tool: when changing whether a link appears in the product's storefront. It also clarifies product scoping, but it does not explicitly mention alternatives or when not to use it, so it stops short of full when/when-not guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains partial update behavior, label replacement semantics, authentication requirements ('Requires Bearer token authentication'), and return value ('Returns the updated link object on success'). This is substantial coverage, though it doesn't address error cases or side effects beyond what's stated.

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 with the main purpose stated first, followed by usage details, return value, and authentication. It is reasonably concise, though the technical reference URL adds a line that might not be strictly necessary for tool invocation. Each sentence contributes meaningful information.

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

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

Given the mutation nature of the tool and the presence of an output schema, the description covers the essential context: partial updates, label replacement, authentication, and return value. It does not mention potential error scenarios or rate limits, but for an update operation with clear schema documentation, 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?

The input schema already has detailed descriptions for all parameters (100% coverage), so the baseline is 3. The description adds value by reinforcing the partial update semantics and emphasizing that labels are fully replaced, which goes beyond the schema's wording. It also clarifies that an empty string clears labels, but that is also in the schema. Overall, the description complements the schema effectively.

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 action: 'Update an existing affiliate link's title, destination URL, or labels.' It uses a specific verb (update) and resource (affiliate link), and distinguishes itself from sibling tools like create_link or get_link by explicitly focusing on modifying an existing 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 provides clear usage context: it explains partial update semantics ('Fields omitted from the call are left unchanged') and warns about label replacement ('Labels are replaced entirely'). However, it does not explicitly mention when not to use the tool or name alternative tools for cases like full replacement or deletion.

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 shoulders the burden and discloses key behavioral traits: partial update semantics, auth requirement, and scope limitation (metadata only, not full branding). It doesn't discuss failure modes or reversibility, but for a simple metadata update these omissions are acceptable.

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 purpose and uses five short sentences, each adding value: fields, partial updates, when-not-to-use, auth, and a reference link. There is no redundancy or 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?

For a simple tool with 3 optional, well-documented parameters and an output schema, the description covers purpose, usage boundaries, auth, and a technical reference. It is complete without needing to explain return values, since the output schema exists.

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 descriptive parameter comments that already explain omission behavior. The description's 'fields omitted are left unchanged' reinforces but does not add meaning beyond the schema. No additional syntax or format details are needed beyond what the schema provides.

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

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

The description uses a specific verb ('Update') and resource ('your Affilio storefront's metadata') and enumerates the exact fields (name, description, layout), clearly distinguishing it from sibling tools like auth.update_link and auth.get_store. It immediately answers what the tool does.

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 explicitly says fields omitted are left unchanged, telling the agent when to use it for partial metadata updates. It also provides a clear exclusion: for full branding updates, use the Affilio dashboard, which names an alternative path. The Bearer token requirement is an additional usage prerequisite.

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 of transparency. It discloses key behavioral traits: follows redirects, returns specific fields, handles Amazon/AliExpress availability specially, and notes the 'available' field can be null when not applicable. This goes beyond a simple surface-level description.

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 with a clear opening line, a bulleted use-case section, and a formatted returns list. Every sentence provides useful information without unnecessary fluff; the length is justified by the tool's complexity.

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 URL checker with one parameter and an output schema, the description is complete: it covers the purpose, use cases, output fields, and special cases (null availability, Amazon/AliExpress). No missing behavioral context is apparent.

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 provides 100% coverage of the single 'url' parameter, including a detailed description and example. The tool description adds no additional parameter-level meaning beyond what the schema already states, so a 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 clearly states the tool's purpose with a specific verb and resource: 'Check the health and destination of a URL (link checker / redirect resolver)'. It outlines distinct capabilities (redirect resolution, HTTP status, page title, product availability) that distinguish it from sibling tools like shorten_url or auth.get_link.

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

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

The description explicitly lists when to use the tool with four bullet-point use cases, which is clear context. However, it does not mention when not to use it or explicitly name alternative tools, so it falls short of a full 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?

No annotations are provided, so the description carries full burden. It discloses output format (base64 PNG, embeddable via data URI), configurable visual properties, and the return fields (url, qr_image_base64, mime_type, powered_by). It does not address side effects or error cases, but for a stateless generation tool this is acceptable. Credit for adding the embeddable data URI tip and return structure.

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 purpose, followed by clearly grouped use cases and a return-value list. It is slightly padded with a marketing tagline and docs link, but remains efficient and scannable. Score 4 rather than 5 due to the extra 'Powered by Affilio.link' line.

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 what, when, and what output to expect, with the input schema covering parameter specifics. It includes a docs link for a technical deep-dive. It is complete for a straightforward generation tool, though it omits potential edge cases like URL validation errors or size constraints, which 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 coverage is 100% with detailed descriptions for all 5 parameters (url, color, rounded, transparent, background_color). The description only generically summarizes 'Color, transparency, and dot style are all configurable,' adding no concrete details 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?

The description opens with a specific verb+resource+scope: 'Generate a branded QR code PNG image for any URL with full visual customization.' It clearly distinguishes from sibling tools like shorten_url and auth.* which handle link management, not QR generation.

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 lists concrete scenarios under 'Use this tool when the user needs to,' including creating scannable QR codes, print-ready materials, and embedding in email/web. It lacks explicit when-not or alternative mentions, but no sibling offers QR generation, so the context 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?

No annotations are provided, so the description fully carries the transparency burden. It discloses key behavioral traits: temporary 30-day expiry, MCP-hosted link, no account/dashboard association, deduplication, pending security verification, and return values. This is exceptionally transparent for a tool with no 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 verbose but well-structured and front-loaded with the core purpose, followed by critical caveats, use cases, and return fields. Every section adds necessary information for this security-sensitive tool, though it is longer than strictly minimal.

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?

Despite the presence of an output schema (not shown in detail), the description enumerates all return fields with types and examples, explains expiry, pending state, QR generation, and deduplication, and provides a documentation link. The tool's behavior, constraints, and response format are fully covered with no obvious gaps.

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

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

Schema description coverage is 100% and the url parameter in the schema already explains what URLs are accepted with an example. The main description adds behavioral context like deduplication and pending verification, but does not add meaningful parameter-level semantics beyond the schema. 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 a specific verb and resource: 'Shorten any URL into a compact, trackable Affilio.link short URL.' It clearly distinguishes itself from sibling tools by stating it is the unauthenticated public shortener, in contrast to auth.create_link for permanent account-owned links. This makes the tool's purpose unmistakable.

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 explicit 'Use this tool when' bullet points covering social sharing, QR generation, clean URLs, and temporary links. It also names the alternative tool (auth.create_link) and explains when to choose it instead, giving clear usage guidance.

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