Affilio Link Tools

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

No annotations present, so description carries full burden. Mentions auth requirements and error envelope for auth failures. Does not disclose idempotence, duplicate handling, or other behavioral traits.

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

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

Efficient and well-structured: single-sentence purpose, elaboration, workflow steps, auth info, and reference link. No wasted words.

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?

Provides workflow and auth context. Has output schema (suggested by context signals). Lacks details on response structure, error types beyond auth, and edge cases like duplicate associations.

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 both parameters. The description adds workflow context but no additional semantics beyond 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 clearly states the tool's purpose: 'Associate an affiliate link with a product in your Affilio catalog.' It explains the association, distinguishes from siblings (only this tool adds product-link relation), and mentions multiple links per 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?

Provides a typical workflow with steps (create_link, create_product, add_product_link) and notes that a product can have multiple links. However, lacks explicit when-not-to-use or alternative 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 fully discloses behavioral traits: archived links are hidden, stop redirecting, but click history and analytics are preserved. It also states authentication requirements and error responses. This exceeds expectations for a soft-delete 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, but slightly verbose with 8 sentences. It efficiently covers purpose, effects, and authentication, though some sentences could be combined.

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 simple tool (1 param, output schema exists), the description covers the main effects, authentication, and error behavior. It lacks mention of success response, but that is likely covered by output schema. Some missing info about reversibility is 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?

The schema description coverage is 100%, and the description adds context beyond the schema by clarifying the effect of archiving on the link's redirect and data preservation. This adds meaningful value.

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 'Archive (soft-delete) an affiliate link' and identifies the resource. It distinguishes from hard deletion by explaining the soft-delete behavior, and implicitly differentiates from sibling create/read/update 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 explicitly says 'Use this instead of hard deletion to maintain historical data', providing clear guidance on when to use and what alternative (hard deletion) to avoid. It also mentions required authentication and provides a link to further reference.

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 fully bears the burden of behavioral disclosure. It details that the tool requires Bearer token authentication, validates the URL, auto-classifies the affiliate network, generates a short URL and QR code, and returns comprehensive response fields including error handling. This is highly 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 well-structured with the main purpose first, followed by detailed explanations. It is not overly long, and every sentence provides useful information. Slightly more conciseness could be achieved by avoiding repetition of the authentication requirement, but overall it is effective.

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 4 parameters, lack of annotations, and existence of an output schema (indicated but not shown), the description covers authentication, expected behavior, response fields, and references a technical guide. It provides enough context for an AI agent to correctly invoke the tool and interpret results.

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 description adds significant value beyond the schema. For each parameter, it explains default behaviors (e.g., auto-fetching title, default project, default destination), supported URL formats for 'url', and how to obtain project IDs. This enriches the schema descriptions.

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 creates a new affiliate link in the Affilio account, specifying the verb 'create' and the resource 'affiliate link'. It distinguishes from siblings like 'auth.get_link' and 'auth.update_link' by noting the response contains data needed for those subsequent calls.

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 the workflow by stating the response contains IDs for subsequent 'get', 'update', and 'add_product_link' calls, but it does not explicitly contrast with siblings like 'shorten_url' or 'generate_qr', which are separate tools. The usage context is clear but not fully exhaustive on when to avoid this tool.

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

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

The description discloses that the response includes the new product's ID (needed for other tools), requires Bearer token authentication, and automatically detects affiliate networks from the URL. No annotations provided, so it carries full burden; it's fairly transparent but omits rate limits or idempotency details.

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

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

Three paragraphs, first sentence states purpose immediately. Each sentence adds value: purpose, product explanation, response usage, auth requirement, reference link. 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?

The description covers purpose, response (product ID), prerequisite auth, and links to docs. Output schema exists so no need to detail return values. It lacks mention of error cases (e.g., duplicate product) but is otherwise complete for a creation tool.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds minimal extra value: it mentions URL accepts affiliate or standard links and that image must be publicly accessible HTTPS (already in 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 clearly states the tool creates a new product in the Affilio catalog, defines products as promotional items, and distinguishes from siblings like auth.create_link and auth.add_product_link by noting the product ID is needed for those operations.

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 the role of products and that they can have multiple links and storefronts, implying use before adding links. It mentions authentication and provides a reference link, but lacks explicit when-to-use vs alternatives or exclusion criteria.

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?

Beyond no annotations, discloses authentication requirements (Bearer token), error handling (auth_error envelope for auth failure or account mismatch), and indicates read-only behavior. No destructive actions implied.

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

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

Three sentences, front-loaded with purpose, then return metadata, then auth/errors. Concise but the technical reference link may be slightly extraneous.

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

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

Given the existence of an output schema, the description appropriately covers authentication, error scenarios, and input source, making it complete for a 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?

Parameter link_id is explained with type, source (from creation or auth.list_links), and example. Description adds contextual usage beyond schema, which has 100% 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?

Clearly states 'Retrieve a single affiliate link by its ID', specifying the action (retrieve) and resource (affiliate link). The description distinguishes from siblings like auth.list_links (listing) and auth.get_link_stats (stats).

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?

Implies usage when having a link_id and needing full metadata, mentioning link_id source (from creation or auth.list_links). However, lacks explicit when-not-to-use or comparison with siblings like auth.list_links for browsing.

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?

Discloses authentication requirement (Bearer token) and data availability caveat (depends on backend configuration). As a read-only operation, no destructive behaviors are relevant.

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

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

Three sentences, each adding value: purpose, data fields with caveat, auth requirement, and reference. Slightly lengthy list but 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?

Given output schema exists, description covers essential aspects: data returned, caveats, auth, and external reference. Could be more complete with rate limits or pagination info.

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 description of link_id. Description adds no additional semantics beyond that.

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?

Verb 'Retrieve' with resource 'click analytics for a specific affiliate link' is specific and distinguishes from sibling tools like auth.list_links 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?

Indicates tool is for retrieving analytics for a specific link and advises using auth.list_links or auth.create_link to get link_ids. Lacks explicit when-not-to-use, but 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?

Describes return fields and authentication requirement, adding value beyond the input schema. Lacks disclosure of error behavior, but adequate for a simple read 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?

Efficient, front-loaded purpose, no wasted words. Each sentence contributes clear 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?

Covers purpose, authentication, and return fields sufficiently given output schema exists. Lacks error handling details, but acceptable for a 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?

Schema already provides full description of product_id parameter including type and source. Description adds minimal additional meaning.

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

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

The description clearly states the tool retrieves a single product by ID, distinguishing it from sibling tools like auth.search_products which return multiple 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?

Provides context for when to use (retrieve single product by ID) and mentions where to obtain the product_id, but does not explicitly state when not to use or compare to alternatives.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool is a read operation via 'Retrieve' and requires Bearer token authentication, but does not discuss side effects, rate limits, or error conditions. The return fields are listed but behavioral details are minimal.

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 (3 sentences plus a link), with the purpose front-loaded. Every sentence adds value: purpose, return data, auth requirement. The link adds some verbosity but 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?

Given the tool has only one parameter and an output schema exists, the description adequately lists return fields and authentication context. It is complete enough for a read-only operation, though it omits error scenarios or pagination (if applicable).

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 already documents the store_id parameter as a MongoDB ObjectId. The description adds no extra information beyond paraphrasing the parameter (by ID), 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 starts with a clear verb+resource combination ('Retrieve an Affilio storefront by ID'), explicitly stating the action and the target. It lists specific returned fields, making it distinct from sibling tools like auth.update_store 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 implies usage for retrieving store configurations but does not explicitly state when to use this tool over siblings (e.g., auth.get_link for links). It mentions authentication but lacks when-not or alternative 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, the description carries full burden. It mentions the return values (status, configuration, credential metadata) and authentication requirement (Bearer token). The presence of an output schema reduces the need to detail return format.

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, with no unnecessary words. It is front-loaded with the main purpose and structured logically.

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 parameters and an output schema, the description provides sufficient context: purpose, return content, authentication, relationship to sibling, and a reference link.

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 are no parameters, so baseline is 4. The description adds context about what the tool returns, compensating for the lack of parameter documentation.

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, with examples of what is returned (Amazon Associates, AliExpress, eBay). It distinguishes from siblings by noting that active integrations are needed for auth.search_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 indicates when to use the tool (to list integrations) and provides context linking to auth.search_products. However, it does not explicitly state when not to use this tool or mention alternatives beyond the single sibling reference.

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. It discloses sorting by creation date (newest first), fields in each item, pagination behavior, and authentication. It lacks mention of rate limits or constraints, but covers core behavioral traits.

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

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

The description is concise (3 sentences + link) and front-loaded with the primary purpose. It efficiently covers key points without superfluous text. Minor improvement could be grouping parameter details more tightly.

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 presence of an output schema, the description does not need to detail return values. It covers parameters, pagination, authentication, and sorting. For a read-only listing tool with good schema coverage, this 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?

Schema coverage is 100%, baseline 3. Description adds value by explaining the purpose of 'skip' and 'limit' for pagination, and 'project_id' for filtering. This is beyond what the schema provides (defaults and constraints) and clarifies usage context.

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

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

The description clearly states the verb 'List' and resource 'affiliate links in your Affilio account', with optional filtering and pagination. This distinguishes it from siblings like 'auth.list_links_ranked' (ranking) and 'auth.get_link' (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?

It explains optional project filtering and pagination, and mentions Bearer token authentication. However, it does not explicitly specify when to use this tool versus alternatives (e.g., 'auth.list_links_ranked' for ranked results), nor does it include when-not or exclusion criteria.

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 full burden. It discloses that it returns the same link schema as auth.list_links but ordered by total clicks descending, mentions pagination behavior, and notes Bearer token authentication. This is good but could be more thorough (e.g., rate limits, error handling).

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. It starts with a clear purpose statement, then explains relationship to sibling tool, use cases, pagination, authentication, and a reference link. Every sentence is informative 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 the presence of an output schema (not shown but indicated), the description need not detail return values. It covers purpose, usage, pagination, and authentication. The tool has only 3 parameters, all documented in the schema, and the description provides necessary context for effective use.

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 parameter semantics are well-covered by the schema. The description adds value by reinforcing pagination usage and explaining that omitting project_id ranks across all projects. This slightly exceeds 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 clearly states 'List affiliate links ranked by click performance' and specifies the ordering by descending click count. It distinguishes from the sibling tool auth.list_links by noting the different ordering, 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 explains when to use the tool: for identifying top-performing links, optimizing content strategy, and spotting underperforming links. It also mentions pagination with skip and limit. While it doesn't explicitly state when not to use it, the context and use cases are 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 provided, so description carries full burden. It states this is a list operation (read-only), returns paginated results in configured display order, and requires authentication. No side effects mentioned, but none expected for a list tool. Good coverage of behavioral traits.

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

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

Two short paragraphs plus a reference URL. Information is front-loaded: purpose first, then output details, then pagination, then auth. No unnecessary words. Could be slightly more concise but overall 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?

With an output schema present, description covers essential context: purpose, pagination, authentication, ordering, and output fields. Does not mention error cases or invalid store_id, but given output schema exists and parameters are well-documented, completeness is adequate.

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 baseline is 3. Description reiterates pagination use for skip/limit and mentions store_id implicitly. Adds the context that products are returned in configured display order, which is not in schema. Marginal value beyond 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?

Description clearly states 'List all products assigned to a specific Affilio storefront', specifying verb and resource. Distinguishes from sibling tools like auth.search_products by implying a full list vs search. Output fields are listed, adding specificity.

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

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

Explicitly describes pagination with skip and limit, and requires Bearer token authentication. However, lacks explicit guidance on when not to use this tool versus alternatives like auth.search_products. Implicit differentiation is present but not explicit.

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

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

With no annotations provided, the description covers authentication (Bearer token), prerequisites, error envelopes, and the live nature of results. It does not mention rate limits or explicitly state it is read-only, but the search semantics imply no 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-structured with clear sections: main purpose, returned data, prerequisites, error envelopes, authentication, and a reference link. Every sentence is informative and non-redundant.

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

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

Given the presence of an output schema, the description still covers return fields, prerequisites, authentication, errors, and the integration workflow. It is fully adequate for an agent to understand how and when to invoke the tool.

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

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

Schema description coverage is 100%. The description adds value for 'query' with natural-language examples and for 'platform' with supported values and a cross-reference to auth.list_integrations. It does not reiterate the 'limit' parameter, but the schema already provides clear details.

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 searches for products on connected affiliate platforms (Amazon, AliExpress, eBay). It specifies the verb 'search' and resource 'products', and distinguishes from siblings by noting results are ready for auth.create_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 lists prerequisites (active integration, check auth.list_integrations) and error envelopes for common failure cases. It provides context on when to use the tool but does not explicitly state when not to use it or compare to alternatives beyond referencing auth.create_product.

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 should disclose behavioral traits beyond the schema. It repeats schema information about visibility effects and mentions authentication, but omits side effects, error conditions, or permission requirements. Minimal added value.

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

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

Two concise sentences plus one line for authentication and a reference link. Front-loaded and efficient with no wasted words.

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 2-parameter mutation with output schema available, the description adequately explains the core functionality but lacks detail on error handling, prerequisites, or response format.

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 clear descriptions for both parameters. The tool description adds no additional meaning beyond repeating schema content, so 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 action ('set public/private visibility') and explains what public and private mean in terms of accessibility and storefront listings. It uniquely identifies the tool's purpose among siblings like auth.update_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 implies usage when needing to change visibility but provides no explicit guidance on when to use this tool versus alternatives like auth.update_link. The authentication requirement is noted but not contextualized.

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 full burden. It discloses partial update behavior, label replacement semantics, and that it returns the updated link object. It also provides a technical reference link. Missing details like error responses or rate limits, but overall sufficient for safe invocation.

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: a clear opening sentence, followed by parameter behavior details, a note on authentication, and a reference link. No fluff, but the reference URL could be a footnote.

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 complexity (4 parameters, 1 required) and presence of an output schema, the description covers all necessary aspects: purpose, parameter behavior, labels replacement, partial update, and return value. It is complete for effective use.

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%, but the description adds context beyond the schema: explains partial update, how labels are replaced, and the effect of omitting fields. This clarifies parameter semantics and reduces ambiguity.

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: 'Update an existing affiliate link's title, destination URL, or labels.' This distinguishes it from sibling tools like create_link and archive_link, making the agent's selection 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 specifies that any combination of fields can be provided, omitted fields are unchanged, and labels are replaced entirely. It also mentions authentication requirements. However, it does not explicitly state when not to use this tool (e.g., preferring other tools for full updates).

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 provided, so description carries full burden. It notes it updates metadata (write operation) and requires Bearer token authentication. It doesn't mention rate limits or error handling, but overall sufficient for a mutation tool. No contradiction.

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

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

Three sentences, each purposeful. First states action, second explains usage, third provides exclusion guidance. Front-loaded and 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?

For a tool with 4 params (1 required), good schema coverage, and existence of output schema, the description covers purpose, usage, exclusions, authentication, and provides a technical reference. Complete and clear.

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 baseline is 3. Description adds value by synthesizing: 'Provide any combination ... fields omitted are left unchanged.' This clarifies behavior beyond individual schema descriptions.

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 explicitly says 'Update an Affilio storefront's metadata' with a specific verb and resource. It distinguishes from sibling tools like auth.get_store, auth.create_product, etc. High clarity.

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 when-to-use: 'Provide any combination of name, description, and layout — fields omitted are left unchanged.' Also states when-not-to-use: 'For full branding updates ... use the Affilio dashboard → Storefront settings.' Explicit 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 full burden. It discloses return format (base64 PNG) and customization options, but does not mention potential limitations (e.g., rate limits, authentication requirements, or side effects beyond image generation).

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 concise, starting with a clear one-liner, then explaining return format, use cases, and return fields. Every sentence adds value, and the overall length is appropriate.

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 core functionality, use cases, and return format. The output schema further documents return values. Some minor details are missing (e.g., URL length limits, error handling), but the tool is simple and well-documented. A link to additional docs is provided.

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 parameter descriptions. The description adds marginal value by noting 'Color, transparency, and dot style are all configurable,' but this largely repeats schema information. 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 states 'Generate a branded QR code PNG image for any URL with full visual customization.' This is a specific verb-resource combination that clearly distinguishes it from sibling tools which focus on link management and URL shortening.

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 four use cases in a bulleted list, providing clear guidance on when to use the tool. However, it does not explicitly state when not to use it or compare to alternative tools, though no alternative QR tool exists among siblings.

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?

Discloses deduplication, affiliate classification, QR code generation, async processing, and expiry. Without annotations, this provides substantial behavioral context, though rate limits or auth requirements are absent.

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

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

Front-loaded with a clear summary, followed by bullet lists for use cases and return fields. Slightly lengthy due to return field details that output schema could cover, but overall 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?

Fully covers core functionality including dedup, classification, QR, async processing, and expiry. No output schema provided, but return fields are comprehensively described. Sibling tools are not needed for completeness.

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 one parameter (url). The description adds value by explaining supported URL types (affiliate networks) and providing an example, exceeding baseline expectations.

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 shortens URLs with affiliate link intelligence, specifying verb and resource. It distinguishes from siblings like generate_qr and auth.create_link by highlighting combined shortening, classification, and 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?

Explicitly lists four usage scenarios (shortening, tracking, QR, compact version). While it doesn't state when not to use or name alternatives, the context is sufficient for decision-making.

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