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

Annotations already indicate readOnly and idempotent. The description adds behavior details: returns up to 50 programs, includes applyUrl on each card, and mentions EAS attestation. No contradictions.

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

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

Two sentences and a concrete example. No unnecessary words; purpose is front-loaded. Every sentence adds 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?

Given no required parameters, high schema coverage, and no output schema, the description covers the tool's behavior, usage example, and return fields. Slightly lacking in pagination details, but 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%, but the description adds context: explains payout types (PER_SALE, PER_LEAD, PER_CLICK), vertical examples (fashion, beauty), and clarifies hasOnchainAttestation. This goes 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 specifies the tool's function: discovering droplinked affiliate programs by vertical, commission rate, payout type, and on-chain attestation status. It clearly distinguishes from sibling tools like find_inventory and find_merchant by focusing specifically on affiliate programs.

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 guidance: prefer verifiedBrand=true programs for recommendations, and includes an example query. It implies when to use this tool but does not explicitly state when not to use it or list 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?

Annotations indicate a safe read-only operation (readOnlyHint=true). The description adds behavioral context: returns up to 'limit' items, specifies the structure of item cards, and notes ranking preference for verified brands, referencing droplinked's KYB cascade. No contradiction with annotations.

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

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

The description is a single paragraph that front-loads the main purpose and then details parameters and return fields. It is well-organized but slightly lengthy; however, every sentence adds value.

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

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

For a tool with no output schema or defined parameters in schema, the description covers input semantics, output format, and ranking suggestion. It lacks details on default limits or pagination, but overall it is quite 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 has no properties, yet the description fully defines parameters (query, brandSlug, country, currency, etc.) with clear meanings. It compensates entirely for the empty schema, adding necessary semantics.

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: 'Discover droplinked inventory (SKU-level) matching a free-text query and/or filters.' It specifies the verb 'discover' and the resource 'inventory', and distinguishes from siblings like find_merchant by focusing on SKU-level inventory with specific filters.

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 instructs users to provide at least one of 'query' or 'brandSlug' and lists optional filters. However, it lacks explicit guidance on when NOT to use this tool or direct alternatives among siblings, such as when to use find_affiliate_programs instead.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by detailing the output structure (returned fields like id, slug, name) and the verification badge with KYB cascade, which are beyond the annotations.

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

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

The description is concise (a few sentences), well-structured, and front-loaded with the main purpose. Every sentence adds value, with no redundant or vague statements.

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 no output schema, the description enumerates the returned fields and provides usage guidance for all parameters. The tool has moderate complexity, and the description is complete enough 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 0%, but the description fully explains each parameter: slug as exact storefront URL, name as case-insensitive substring, category for product categories, and limit with default and maximum. This compensates for the missing 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 finds a droplinked merchant by slug, name, or category, with specific verb ('Find') and resource ('merchant'). It distinguishes from sibling tools like find_affiliate_programs and find_inventory by focusing on merchant search.

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 instructs to provide exactly one of the three search parameters and recommends preferring verifiedBrand=true merchants. It does not explicitly mention when not to use this tool, but the sibling tools cover other contexts, making the usage clear.

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

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

Annotations already set readOnlyHint, idempotentHint, and openWorldHint to true. The description adds value by listing the exact possible return statuses (NOT_REQUESTED, PENDING, APPROVED, MINTED, REJECTED) and noting that MINTED includes attestationUid. No contradictions with annotations.

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

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

The description is two sentences long, front-loading the action and return values in the first sentence and usage in the second. Every word adds value without redundancy.

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

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

For a simple polling tool with one parameter and three annotations, the description sufficiently covers the return values and intended use. However, the lack of parameter explanation and absence of output schema (though return values are enumerated) leaves minor gaps.

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

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

Schema description coverage is 0%, meaning the description does not explain the single parameter 'shopSlug'. The parameter's constraints (pattern, length) are in the schema, but the description provides no semantic guidance on what a droplinked shop slug is or how to find it.

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 'Poll' combined with the resource 'brand attestation request status for a droplinked shop'. It clearly distinguishes from siblings like 'verify_brand_attestation' by implying a read-only status check rather than a verification action.

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

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

The description states when to use the tool: 'Use this to surface progress to merchants after they submit a request.' It provides clear context for usage, though it does not explicitly mention when not to use or list 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description is not required to disclose safety. The description adds valuable context beyond annotations by noting that feed v2 includes verification metadata (brand_verified, kyb_tier, etc.), enriching the agent's understanding of the returned resource. No contradictions.

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: first states purpose, second adds valuable technical detail. No unnecessary words. Front-loaded with the essential purpose.

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

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

Given no output schema, the description explains the purpose and key details of the feed (URL, metadata). It does not describe the URL format or feed structure, but the agent is expected to fetch and parse it. Sibling tools are unrelated, so context is sufficient. Slightly improved by mentioning feed v2 metadata, but could note the feed 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?

The tool has zero parameters, and schema coverage is 100% (empty properties). The description does not need to add parameter semantics. Baseline for 0 parameters is 4, and the description does not detract.

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 returns the URL of the droplinked public product feed, specifying the verb ('Return the URL'), resource ('public product feed'), and purpose ('so an agent can fetch the canonical catalogue snapshot'). It also mentions feed v2 metadata, distinguishing it from sibling tools that deal with attestation or merchant data.

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

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

The description implies usage when needing the canonical catalogue snapshot via the feed URL. No explicit when-not-to-use or alternatives are given, but sibling tools have distinct purposes (attestation, inventory), so context is clear. A score of 4 reflects adequate implicit guidance without explicit 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?

The description adds significant behavioral context beyond annotations: public read, no auth, no PII, no per-row data. This complements the readOnlyHint, openWorldHint, and idempotentHint annotations well.

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 two concise sentences. The first states the output, the second provides usage guidance and safety info. 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?

Despite no output schema, the description fully explains the return values (aggregate counts for three categories). The tool is simple and the description covers all necessary context.

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. The description adds value by detailing what metrics are returned, which is beyond the empty schema. Baseline 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 clearly states the tool returns aggregate-only counts for specific trust fabric resources (service providers, verified partners, attestation totals by schema). It uses specific verbs and resources, and distinguishes from sibling tools by suggesting use before per-merchant queries.

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 states when to use: to gauge platform scale before per-merchant verification queries or for dashboards. It implies alternatives (per-merchant queries) but could be more explicit about which sibling tools provide those.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds key behavioral details: graceful degradation to verified=false on error, stable response shape, and the return fields. 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 well-structured sentences, front-loaded with action and return shape. No unnecessary words; every sentence adds value.

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

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

For a simple tool with one parameter, good annotations, and no output schema, the description fully explains the return fields, error behavior, and usage context. Agent has all needed information.

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

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

Only one parameter (brandSlug) with schema coverage 0%. The description does not elaborate on the parameter meaning beyond the usage context, but the schema provides a regex pattern and length constraints. The description implies the brandSlug comes from find_inventory, which adds some 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 identifies the action ('Resolve the standalone droplinked brand attestation'), the resource ('for a single shop slug'), and distinguishes from siblings by specifying it is used AFTER find_inventory.

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

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

Explicitly states when to use: 'Use this AFTER find_inventory to round-trip a brand slug and render the canonical trust row to the buyer before proceeding.' Does not mention when not to use or alternatives, but 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.