droplinked

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

The annotations already communicate that this is a mutating, non-idempotent operation, so the bar is lower. The description adds valuable behavioral details beyond the annotations: the exact return shape `{ status, cartId, lineCount }`, the meaning of lineCount, and the structured failure reason enum (CART_NOT_FOUND, SKU_NOT_FOUND, etc.). This helps the agent handle errors and retries appropriately.

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 tight and front-loaded: the first sentence gives the core purpose, the second gives usage context, and the third covers return value and error handling. Every sentence earns its place without redundant detail, making it both comprehensive 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?

Given the tool has 4 parameters, no output schema, and annotations that only cover basic mutability, the description covers the essential aspects: what it does, when to use it, prerequisites, return contract, and failure modes. The only minor gap is the missing meaning of the referrer parameter, but overall this is sufficiently complete for an agent to invoke the tool correctly.

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

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

With 0% schema description coverage, the description carries the burden of defining parameters. It explains skuId as a product variant, quantity as quantity, and cartId as coming from start_checkout or a prior call, but it does not explain the optional referrer parameter. This leaves a gap in understanding the full parameter set.

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 'Add a product variant (skuId) and quantity to an existing droplinked cart', which is a specific verb+resource statement that clearly distinguishes this from sibling tools like cart.removeLine and cart.updateLineQuantity. The additional context 'Use this to build a multi-item cart incrementally before checking out' reinforces the tool's specific role.

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 the tool ('build a multi-item cart incrementally before checking out') and provides a clear prerequisite ('Requires a cartId from start_checkout... or a prior cart.addLine call'). It does not explicitly contrast with alternatives like updateLineQuantity, but the context makes the usage scenario unambiguous.

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

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

The description discloses significant behavioral context beyond annotations: exact return fields, unit semantics (minor units), error handling with specific error codes, and invocation order. Annotations only mark idempotency/safety flags; the description enriches the agent's mental model of failures and responses without contradicting any 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 compact yet information-dense: each sentence adds value (purpose+return, unit explanation, invocation order, error taxonomy). It is front-loaded with the core behavior and uses structured notation for error codes, making it easy to parse.

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 lack of an output schema, the description fully specifies return values and units. It also covers error conditions and execution context, which is essential for an agent to know when and how to invoke the tool. No critical gaps for the tool's complexity.

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 0%, so the description carries the full burden for parameter meaning. It clarifies 'discountCode' as a coupon code implicitly, but provides no explicit input format, validation rules, or interaction between parameters. The description focuses on output and errors rather than enriching input 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 states the exact action ('Apply a discount or coupon code to a droplinked cart') and clearly differentiates from sibling cart tools by focusing on discount application. It also specifies the return object, leaving no ambiguity about the tool's purpose.

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 explicit sequencing guidance ('Call this after cart.addLine and before start_checkout / process_payment') and hints at alternative actions (retry with a different code or proceed without a discount). It lacks a formal 'when not to use' statement, but alternatives are not present among siblings, making the guidance 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?

The description contradicts the annotations: it states the line is 'deleted from the cart' (a destructive action) while the annotations set destructiveHint=false. Per rubric, this contradiction forces a score of 1.

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 five focused sentences covering action, outcome, return value, alternative, and error handling. Each sentence adds necessary information with no filler.

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

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

Despite the annotation contradiction, the description itself is thorough: it defines the operational effect, return payload, deterministic error codes, and the appropriate sibling alternative. This is sufficient for an agent to invoke the tool correctly, given the simple two-parameter schema.

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

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

With 0% schema description coverage, the description compensates by clarifying that skuId identifies the line to be removed and that cartId is part of the return payload, implying its role as the cart identifier. However, cartId is not explicitly described, preventing a higher score.

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 ('Remove a product line from a droplinked cart by skuId') and clearly distinguishes itself from the sibling tool cart.updateLineQuantity by noting that quantity changes should use that tool instead.

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 states when to use this tool (to fully remove a line) and when not to (to change quantity), naming the alternative cart.updateLineQuantity. This provides clear decision guidance for an agent.

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

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

The description adds substantial behavioral context beyond annotations. It discloses the return format, identifies lines by skuId (the variant id used when added), and lists specific error reasons (CART_NOT_FOUND, LINE_NOT_FOUND, INVENTORY_INSUFFICIENT, etc.). It also clarifies that quantity=0 is not for removal, which is a subtle behavioral note. 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 three sentences, each serving a distinct purpose: action and identification, return format, and alternative usage plus error handling. It is front-loaded with the primary purpose and avoids unnecessary detail, making it highly efficient and well-structured.

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

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

Given the tool's simplicity and the absence of an output schema, the description provides complete context: it explains what the tool does, how it identifies lines, what it returns, when to use an alternative, and what errors to expect. This is sufficient for an agent to select and invoke the tool correctly with no 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?

With 0% schema description coverage, the description compensates by explaining that skuId is the variant id used when the line was added. Quantity is contextually clear as the new quantity, and cartId is self-explanatory in the cart context. However, it does not explicitly describe cartId or the validation constraints beyond what schema provides, so it's not perfect.

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 function: 'Change the quantity of an existing line in a droplinked cart.' It specifies the resource (cart line), the action (update quantity), and the identification method (skuId). It distinguishes itself from cart.removeLine by explicitly noting that removal should use that tool, and from cart.addLine by the update vs add nature.

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 provides an alternative: 'Use cart.removeLine to remove a line entirely instead of setting quantity=0.' This gives clear when-to-use and when-not-to-use guidance. Additionally, the structured error reasons inform the agent on how to handle failures, which aids in deciding when to retry or fall back.

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. The description adds behavioral details beyond that: 'Returns up to 50 programs creators can apply to via the applyUrl on each card' and explains that the verified badge is backed by 'droplinked's EAS attestation chain'. This gives the agent useful context about result limits and attestation semantics without contradicting 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 three sentences long and front-loads the primary purpose. It includes a useful example and the key guidance about verifiedBrand, with no filler or repetition. Every sentence earns its place.

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

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

While there is no output schema, the description mentions the applyUrl on each card, giving some return-shape context. It covers the main filtering dimensions, a usage example, and the attestation meaning. Given the tool's moderate complexity and rich annotations, the description is sufficient but does not fully elaborate on all possible result fields or pagination beyond the 50-item cap.

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 all parameters, each already explaining its meaning (e.g., 'Vertical slug — fashion, beauty, tech, fitness, etc.'). The description adds an example invocation but does not provide any new parameter semantics beyond the schema. With full schema coverage, the baseline is 3, and no extra parametrical insight is 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 the tool's purpose: 'Discover droplinked affiliate programs by vertical, commission rate, payout type, and on-chain attestation status.' It identifies the resource (affiliate programs) and the filtering capabilities, distinguishing it from sibling tools like find_inventory or find_merchant. The verb 'Discover' is specific and conveys the read-only nature.

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 a concrete example ('a creator asks what fashion programs pay 15%+ with on-chain verified attestation? → call find_affiliate_programs(...)') which implicitly tells the agent when to use this tool. It also advises preferring verifiedBrand=true programs, giving clear context. However, it does not explicitly mention when not to use it or compare directly to alternatives, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses substantial behavioral details: merchant emails are dropped at the MCP boundary, authentication requires a Bearer JWT with a specific scope via a two-header model, and invalid/missing credentials degrade to an empty envelope. It also describes the output shape (rows with tier and 4 facets, plus a rollup aggregate). This goes far beyond what annotations provide.

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 dense sentences, each carrying essential information: purpose, output, brand-exposure constraint, and authentication. It is front-loaded with purpose and avoids fluff, though it is slightly longer than 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?

Given the tool's complexity (nested criteria, no output schema), the description provides a good high-level picture: what it searches, what it returns, and how auth/errors behave. It does not detail the exact output schema or all parameter semantics, but it is complete enough for an agent to understand the tool's role and safety profile.

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%, so the description must compensate for parameters. It mentions 'credit tier' and 'ranking facet', which maps to criteria.tier and criteria.sortBy, but it uses different enum names ('sales-efficiency' vs 'efficiency', 'operational risk' vs 'risk') than the schema, which could confuse the agent. It also does not explain the nested criteria object structure, nor limit, order, windowDays, or agentBearer. The partial mapping is not enough to fully compensate.

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 a specific verb ('Search') targeting a specific resource ('KYB-verified droplinked merchant cohort grid') with scoping criteria ('by credit tier and ranking facet'). It also distinguishes itself from sibling tools by its lender-agent use case and the unique cohort grid, making it clear what this tool does and how it differs from find_merchant or other search 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 states when to use it: 'Used by lender-agents to answer which merchants match my underwriting box?' It also provides a when-not via the brand-exposure discipline, saying lenders should use the marketplace offer flow, not direct outreach. However, it does not name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds valuable behavior: aggregates multiple catalog sources, returns up to limit InventoryItemCards with a detailed field list, and ranks verifiedBrand items based on KYB. Minor gaps remain, such as how query and brandSlug combine and the exact structure of nested objects like pricing.

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 dense but every sentence earns its place: main purpose, required inputs, optional filters, output format, and ranking guidance. It is front-loaded with the core function and logically structured, with no redundancy with annotations.

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?

There is no output schema, so the description's field list is the only return specification, and it includes optional markers and a ranking note. For a complex 10-parameter search tool, it covers essentials but leaves sub-structure of pricing/availability unexpanded.

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 has 0% description coverage across 10 parameters. The description compensates fully by explaining every parameter's meaning, including query as catalog match, brandSlug as scope, country as ISO-3166, currency examples, price bounds, verifiedBrand as attested only, inStockOnly, and source with its enum values. It also introduces the at-least-one-of constraint.

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 ('Discover') with a clear resource ('droplinked inventory (SKU-level)') and scope ('across every connected catalog source'), naming the exact sources. This distinguishes it from sibling tools like search_products or get_product.

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

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

The description explicitly states the required input ('Provide at least one of query or brandSlug') and lists all optional filters with their allowed values. It also gives ranking guidance ('Prefer verifiedBrand=true'). However, it does not explicitly name sibling alternatives or state when not to use the tool, so it falls short of a 5.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantive behavior: slug matches exact storefront URL, name is case-insensitive substring, category matches merchants with products in that category, and return fields are listed. The note about KYB cascade behind verifiedBrand provides additional trust 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?

Three sentences cover purpose, parameters, return shape, and recommendation guidance. The information is front-loaded and every sentence 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?

Despite lacking an output schema, the description enumerates MerchantCard fields, defines matching semantics for all search keys, and explains when to prefer verifiedBrand. This is complete for a read-only lookup tool with four optional-in-schema but logically constrained parameters.

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 has no parameter descriptions, but the description fully compensates by explaining each parameter: slug, name, category, and limit. It also clarifies the one-of constraint and the meaning of 'up to limit'.

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: 'Find a droplinked merchant by slug, name, or category.' It clearly distinguishes itself from sibling tools by focusing exclusively on merchant lookup and listing exact search criteria.

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

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

Explicit guidance is given: 'Provide exactly one of: slug, name, or category' and 'Prefer verifiedBrand=true merchants when citing recommendations.' It does not mention alternatives like search_products or get_product, but the usage context is otherwise 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?

The description expands on the annotations (readOnlyHint, idempotentHint) by detailing the specific statuses returned and noting that MINTED includes attestationUid, which is beyond what structured data provides. It does not contradict annotations and adds useful behavioral context about the polling nature of the 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 exactly two sentences, front-loaded with the core action and return values. Every sentence serves a purpose: the first states what the tool does, the second lists outputs and when to use it. There is no wasted wording.

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 single-parameter polling tool, the description is thorough. It covers the action, the possible return values, and the intended use case. Since no output schema is provided, the description's enumeration of statuses and the attestationUid detail fully cover return value expectations. The annotations handle safety and idempotency, so no further context 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 description does not directly explain the shopSlug parameter, and schema description coverage is 0%. However, the single parameter is self-explanatory from its name and schema constraints (pattern, min/max), and the description references 'droplinked shop,' which aligns with the parameter. The schema's strong constraints compensate somewhat, but the description could have explicitly linked shopSlug to the shop 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 uses the specific verb 'Poll' with the resource 'brand attestation request status for a droplinked shop,' clearly distinguishing it from sibling tools like request_brand_attestation and verify_brand_attestation by focusing on status retrieval. It also lists the exact possible return states, leaving no ambiguity about 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?

The description provides explicit usage context: 'Use this to surface progress to merchants after they submit a request.' This clearly indicates when to use the tool, but it does not explicitly name alternatives or state when not to use it. However, the context is sufficient to guide an agent's decision 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?

Despite `readOnlyHint` and `idempotentHint` being present, the description adds valuable behavioral context: 'Gracefully degrades to `found=false, items=[]` on 404 / transport error' and notes the per-cohort nature of the checklist. This goes beyond the annotations by explaining failure modes and variability.

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 three sentences, front-loaded with the primary action, followed by return structure, usage context, and error behavior. Each sentence provides distinct value with no redundant or filler content.

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 there is no output schema, the description compensates by listing the return fields and rollup counts, and by noting the graceful degradation. It lacks detail on authentication prerequisites (agentBearer) and does not fully explain the 'cohort' concept, but overall it provides sufficient context for a read-only 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 description coverage is 0%, and the description does not explicitly explain parameters. It implicitly identifies `applicationId` as the lending application identifier, but `agentBearer` is left undefined. The description fails to compensate for the lack of schema-level descriptions, leaving the optional auth parameter ambiguous.

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 'Resolve[s] the per-cohort document upload checklist for a merchant's lending application' and specifies the return structure. It distinguishes itself from siblings by focusing on document checklist items and rollup counts, a unique resource among the tool list. The verb 'Resolve' is somewhat indirect, but the details make 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 explicitly says 'Use this to surface upload progress for lender-agent consumers without re-implementing the document state machine,' giving a clear context for when to invoke. It does not mention exclusions or alternatives, but the use case is specific enough to guide selection.

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 bar is lower. The description adds value by disclosing that the tool returns a URL (not feed data itself), mentions 'feed v2,' and lists the verification metadata fields included. This goes beyond the minimal safety profile.

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 with no filler. The first sentence front-loads the purpose and return value; the second adds a relevant detail about feed contents. Every sentence earns its place.

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

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

For a zero-parameter, read-only, idempotent tool, the description adequately communicates what is returned (URL), why it's used (canonical catalog snapshot), and a content detail (verification metadata). No output schema exists, but the description covers the return type adequately. Minor gaps such as URL format or authentication are not critical for this simple 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, so the schema fully describes the input signature. The baseline for 0-param tools is 4, and the description does not need to add parameter explanations.

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 a specific resource: 'the URL of the droplinked Stripe ACP product feed.' The purpose is further clarified as enabling the agent to 'fetch the canonical catalog snapshot,' which distinguishes it from sibling tools like get_product or 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 implies the tool is for obtaining a canonical catalog snapshot, but it does not explicitly contrast this with alternatives (e.g., get_product for individual products) or state when not to use it. Usage context is present but no exclusions or alternatives are named.

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, openWorldHint, and idempotentHint. The description adds valuable context beyond that: the tool returns only 'occurredAt + eventType + status transitions' and redacts operator-only fields (actorId, reason, raw value diffs). This clarifies the public nature of the data and the exact response scope.

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, all packed with essential information: what it returns, when to use it, and what is redacted. No fluff or repetition of schema/annotations.

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 no output schema, the description fully explains the return structure (occurredAt, eventType, status transitions) and what is excluded (operator-only fields). For a simple single-parameter read tool, this is sufficient to invoke and interpret the result.

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

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

The schema has one parameter (lenderId) with 0% description coverage. The description mentions 'registered lender' but does not explicitly name or describe the lenderId parameter. Since the parameter is simple and inferable from the tool name, the description partially compensates, but it could still add details about the ID format or example values.

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: 'Return the public lifecycle timeline... for a registered lender.' It also explains the exact use case (verifying ACTIVE status at attestation time), which clearly distinguishes it from sibling tools like get_methodology_timeline or get_lending_application_status.

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 this tool is used: 'Used by verifiers to determine whether a lender was ACTIVE at the time a Schema B credit-risk attestation was minted.' It gives a clear context without explicitly naming alternative tools, but the particular scenario is well-defined.

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 the annotations (readOnly, idempotent, openWorld), the description adds valuable behavioral details: it specifies the returned envelope fields (status, lending tier, cohort, partner ref, decision timestamps, rejection reason) and explicitly states graceful degradation to `found=false` on 404/transport error. This goes beyond what annotations convey.

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 three sentences, each adding distinct value: purpose, return/use case, and error behavior. It is front-loaded with the primary action and contains no redundant or promotional language.

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 sufficiently describes the return value with the envelope fields. It also covers error handling, usage context, and the required parameter. For a single-parameter read tool with readOnly annotations, this is complete and self-contained.

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?

With 0% schema description coverage, the description compensates by clarifying the purpose of the key parameter: 'by applicationId.' However, it doesn't mention the optional `agentBearer` parameter at all, leaving its meaning to inference. The main parameter is well-addressed, but the second parameter is ignored, giving it below full marks.

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 verb and resource: 'Resolve the current status of a merchant's lending application by applicationId.' It distinguishes itself from siblings by emphasizing it returns the 'canonical envelope' and is used for surfacing application progress without re-implementing the state machine, which differentiates it from listing or history 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 clear context for when to use the tool: 'Used by lender-agent MCP consumers to surface application progress without re-implementing the state machine.' This implies it's the canonical single-application status lookup, but it doesn't explicitly mention alternatives or exclusions like sibling tools for listing or history.

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, openWorldHint, and idempotentHint, indicating safe read behavior. The description adds value by specifying that the timeline is 'public' and that 'operator-only fields (actorId, reason) are redacted,' disclosing data privacy behavior. It also lists the return fields (occurredAt, eventType, status transitions), going beyond what annotations convey.

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 three sentences, each serving a distinct role: core function, use case, and return/redaction details. 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?

The description covers purpose, use case, return value, and redaction. It does not explain parameter semantics or error behavior, but for a read-only, idempotent tool with annotations, it provides sufficient context for an agent to understand the tool's role and expected 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?

The schema has zero description coverage for the two required parameters. The description only implies that methodologyHash refers to a 'specific methodology version' and lenderId is part of the request, but it does not explain their formats or roles. With such low schema coverage, the description should compensate more explicitly.

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 has a specific verb ('Return'), resource ('public lifecycle timeline'), and scope ('for a specific methodology version'), and lists the statuses (REGISTERED/SUPERSEDED/REVOKED). It also distinguishes from sibling tools like get_methodology_versions and verify_methodology by specifying its use for determining active status at minting time.

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 clearly states the intended use: 'Used by verifiers to determine whether a methodology was ACTIVE at the time a Schema B credit-risk attestation was minted.' This provides clear context for when to use the tool, though it does not explicitly name alternatives or 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?

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by specifying the ordering (newest-first), the full set of returned fields, and statuses (ACTIVE/SUPERSEDED/REVOKED), which goes beyond what annotations reveal.

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 deliver all essential information: the first defines the action and output contents, the second explains usage context and relationships to sibling tools. No wasted verbiage, well 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?

Despite lacking an output schema, the description enumerates all output fields and statuses, making the return format clear. It also covers usage context and alternatives, which is more than adequate for a simple read-only tool with one parameter.

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 a single lenderId parameter with a clear regex pattern, making it fairly self-documenting. The description doesn't explicitly explain lenderId, but the parameter name and schema pattern are sufficient for an agent to infer its meaning. With 0% schema description coverage, the description could have added a brief mention, but the minimal risk makes this acceptable.

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

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

The description clearly states the tool returns all methodology document versions for a lender, newest-first, and lists the included fields. It also distinguishes itself from related tools by referencing verify_methodology and get_methodology_timeline for different lookup purposes.

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 that verifiers use this tool to trace a lender's full methodology lineage, and provides direct guidance on when to use alternatives (verify_methodology for hash-specific lookups, get_methodology_timeline for per-hash lifecycle events). This is exactly the kind of when-to-use guidance needed.

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. The description adds valuable context about the response's verification block fields and the agent's role as verification UX, going beyond the annotations without contradicting them.

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, front-loaded with the core purpose. The second sentence includes useful output details and a policy note, though 'Per the droplinked council' is slightly verbose. 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?

For a single-parameter get-by-id tool with good annotations, the description covers purpose, main outputs, and how to handle the verification block. No output schema exists, but the description enumerates key response fields, leaving no major 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 has one parameter, productId, with 0% description coverage. The description implies productId identifies a single droplinked product, and the parameter name is self-explanatory, so the description compensates adequately despite not explicitly defining 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 clearly states the tool fetches full public detail for a single droplinked product, listing included content (variants, SKUs, media, shop info). This specific verb+resource+scope distinguishes it from siblings like list_shop_products and get_brand_attestation_status.

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 it—when full product detail and verification data are needed for a single product—and instructs the agent to surface the verification block in cited recommendations. It doesn't explicitly compare with alternatives, 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the trustLevel monotonic-floor rule with down-tiering on default, the exact return envelope shape, and graceful behavior on partial failures. This is substantial behavioral context not available in 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?

Four sentences with zero filler. Front-loaded with the purpose, then return structure, trustLevel algorithm, parameter usage, and failure behavior. Every sentence earns its place.

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

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

For a composite read tool with no output schema, the description covers the return shape, trustLevel logic, parameter conditions, and failure behavior. It is complete enough for an agent to invoke correctly without additional 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?

With schema description coverage at 0%, the description compensates by explaining that brandSlug includes the brand attestation slice and when to omit it. merchantId's role is implied as the essential identifier, but the description adds meaningful nuance to the optional parameter.

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 the specific verb 'compose' and clearly identifies the resource as a 'merchant's full trust dossier' assembled from three named EAS schemas. It distinguishes itself from sibling tools like get_brand_attestation_status or verify_credit_risk by framing this as a consolidated read across multiple schemas.

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 conditional parameter guidance ('Pass brandSlug when known... omit when only merchantId is available') but does not explicitly state when to prefer this tool over alternatives. The phrase 'Three reads, one envelope' implies consolidation as a use case, but no direct comparison or exclusion of sibling tools is given.

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 the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds valuable behavioral context: 'Public read, no auth, no PII, no per-row data.' This clarifies the safety profile and data sensitivity, which is useful for an agent deciding when to call the tool and what to expect in responses.

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, with the main purpose front-loaded in the first sentence. The second sentence adds usage guidance and constraints without repetition or fluff. Every clause earns its place, making the description compact yet informative.

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 nature (no parameters, no output schema), the description fully covers what the tool does, what data it returns, and when to use it. It mentions public accessibility, absence of PII, and aggregate-only behavior. There are no obvious gaps for an agent to invoke this 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 tool has zero parameters, and the schema coverage is 100% (empty properties). The description adds meaning by explaining what is counted, but since there are no params, there is nothing to elaborate. The baseline of 4 for a no-parameter tool applies because the description compensates for the lack of parameter details by clarifying the output scope.

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 'Return aggregate-only counts of the droplinked trust-fabric trinity', clearly stating the verb (return), resource (trust-fabric stats), and scope (aggregate-only). It enumerates specific data categories (registered lenders, service providers, methodology versions, on-chain attestations by schema), which distinguishes it from sibling tools that perform per-merchant verification or return detailed records.

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 usage context: 'Use this to gauge platform scale before issuing per-merchant verification queries or to render a partner-facing dashboard.' It also states what it is not for ('no per-row data'), implying alternatives that provide per-merchant details. However, it does not explicitly name sibling tools as alternatives, so it stops short of full 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the composite structure, the edge case around lenderCurrentStatus vs. attestation status, and graceful clean-slate behavior on errors or unknown merchants. This is rich, decision-relevant behavioral disclosure.

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 dense and front-loaded with the output composition. It is longer than minimal, but every sentence conveys a necessary nuance (output breakdown, efficiency, usage scenario, edge case, error behavior). Slightly verbose but well-structured.

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

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

For a complex tool with no output schema, the description provides the key decision input (anchorTier), a critical status nuance, and error behavior. However, it relies on domain knowledge of 'Schema B' and 'Schema C' without explaining their contents, leaving some gaps for an agent unfamiliar with the underlying structures.

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 (merchantId) exists with schema coverage at 0%, but the schema fully defines the constraints (pattern, length) and the parameter is self-evident from the name. The description does not explain merchantId directly but mentions behavior for unknown merchants, adding marginal value over the schema.

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

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

The description clearly states the tool returns a composite merchant-wide underwriting envelope, enumerating specific components (Schema B, Schema C, CreditTier upgrade preview, summary block). It distinguishes itself from sibling verifier tools by noting it consolidates 3-4 per-axis calls into one.

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 when a lender-agent needs to resolve should I underwrite this merchant + at what tier in one round trip.' It also implies the alternative (multiple verifier calls) but does not name specific sibling tools or provide 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?

Annotations cover readOnly, openWorld, and idempotent, but the description adds substantial behavior: it describes the return fields (observedTier, gaps), tier rules (T1/T2/T3 conditions), null behavior at T3, and graceful error envelope on backend error or unknown merchant. This is valuable context beyond 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 front-loaded with purpose, then structured into return fields, the aspirational caveat, usage instruction, tier ladder, null behavior, and error handling. Every sentence adds value, and the length is justified by the complexity of the tier rules.

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 no output schema, the description explains what is returned (observedTier, gaps) and covers edge cases (null at T3, error envelope). It also details the tier ladder and the relationship to actual issued tier, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 0% for the single merchantId parameter, but the description compensates by repeatedly referencing 'merchant' and explicitly mentioning 'unknown merchant' in the error envelope, making the parameter's role clear. The parameter name itself is self-explanatory, so despite no direct parameter description, the meaning is well conveyed.

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: 'Aspirational roadmap to higher credit-tier ceilings for a merchant.' It clearly distinguishes itself from the actual tier computation by stating 'ASPIRATIONAL only — the actual issued tier on a Schema B attestation also depends...', which separates it from sibling tools.

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

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

Provides explicit when-to-use guidance: 'Use this on merchant-portal flows asking "what does it take to climb to a higher tier ceiling?"'. Also gives a when-not via 'ASPIRATIONAL only', contrasting with actual issued tier determination. This is clear context with exclusion.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: the exact fields returned (applicationId, status, tier, cohort, purpose, requestedAmount, term, decision timestamps), the countByStatus rollup, the non-paginated summary nature, and the auth requirement (Bearer token via two-header model, merchant-or-operator JWT). This goes beyond annotations and aids 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?

Three sentences, each earning its place: purpose+return, use case, auth. No filler or redundant restatements of the name or schema. 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?

For a read-only list endpoint with no output schema, the description covers the return payload, use case, and auth. It lacks details on error conditions or the exact meaning of 'two-header model,' and does not contrast with get_lender_history. However, it is sufficiently complete for a tool with simple parameters and strong annotations.

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%, so the description must compensate for parameter meaning. It does not. The parameters merchantId and agentBearer are not explained; merchantId is only described by a regex pattern in the schema, and agentBearer's connection to the 'two-header model' is ambiguous. The description mentions auth but does not map it to the agentBearer parameter, leaving the agent underinformed.

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 function: 'List a merchant's lending application history.' It identifies the specific resource (merchant lending applications), the action (list), and provides details about the returned data (compact summaries, countByStatus). It distinguishes from siblings like get_lending_application_status by emphasizing full history and compact rollups.

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: 'Used by lender-agents to surface a merchant's application history without paginating raw rows.' This tells when and why to use the tool, implying it replaces a paginated raw list. It does not explicitly mention alternative tools or exclusions, but the context is clear enough.

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

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

Annotations already mark as readOnly and idempotent, and the description adds that each response includes a `shop_verification` block shared across all products on the page due to per-merchant KYB, plus a parallel `verifications` array. It also instructs the agent to surface verification status to the user, adding useful response-handling context beyond the safety profile.

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, with the primary action in the first sentence and the pagination/verification details in the next two. Every sentence adds relevant operational context 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 2-param list tool with no output schema, the description covers pagination, key response elements (shop_verification, verifications), and the user-facing instruction. It omits error cases and sorting/filtering, but those are outside the core purpose and siblings cover product details.

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 has no parameter descriptions (0% coverage), but the description explains shopSlug as identifying the single shop and cursor for pagination. It doesn't state cursor is optional or format, but the context is sufficient for these two simple parameters.

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 'Page through the public catalog of a single droplinked shop by slug', which specifies the action (paging through), resource (public catalog of a single shop), and key parameter (slug). This distinguishes it from sibling tools like search_products (cross-shop search) and get_product (single 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 implies usage when you need all products from one shop and need to paginate, with explicit instruction to use the returned cursor for additional pages. It does not name alternative tools or say when not to use it, so it's clear context but lacks 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 annotation idempotentHint=false is directly contradicted by the description's statement 'Idempotent on acpIntentId — a second call with the same intent returns the prior outcome with replay=true.' This is a clear annotation contradiction, and per the rubric the score is 1 regardless of other behavioral 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?

The description is four sentences with no fluff. It front-loads the core purpose, then gives the workflow sequence, idempotency behavior, and return shape—each sentence earning 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?

Despite no output schema, the description details the return format and statuses. It also covers the call sequence and replay behavior. However, the parameter coverage gap and the idempotency contradiction prevent full completeness, so a 4 is appropriate.

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%, so the description must compensate. It only adds meaning for acpIntentId (as the idempotency key) and holdId (as the 'optional inventory hold'), leaving orderId, agentBearer, and consumerAgentKind entirely unexplained. This is insufficient compensation for 5 parameters.

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 'Finalize a droplinked order using a Stripe ACP payment intent and an optional inventory hold,' which clearly states the specific action and resource. It distinguishes itself from sibling tools (e.g., quote_inventory_available, find_inventory) by being a finalization/payment step, not a quotation or lookup.

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 it: 'The consumer agent calls this after find_inventory + quote_inventory_available + Stripe ACP create_payment_intent.' It also says it 'Closes the agent-to-agent transaction loop,' providing clear usage context and sequencing. This meets the 5-point standard of explicit 'when' 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?

The description goes well beyond the annotations. It discloses that the backend persists the row, stamps a quoteId, surfaces it on the marketplace, and that merchant acceptance anchors it into the Schema E attestation flow. It also reveals the scaffolded status and the exact degraded response until the backend ships. This is rich behavioral context with no contradiction to 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 information-dense but well-structured. The first part states the action and key parameters, the second explains the backend behavior and flow, and the scaffolded caveat is clear. No redundant sentences; every clause contributes to the agent's understanding. It is appropriately sized for 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?

Given the tool has no output schema and 7 parameters, the description covers the main behavioral aspects: persistence, quoteId generation, marketplace surfaces, and the attestation flow. It also explains the current scaffolded limitation. It does not specify the full success response structure, but mentions the quoteId, which is the key output. Overall, it is sufficiently complete for an agent to use the tool 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?

With 0% schema description coverage, the description carries the burden. It explains the semantics of five key parameters (cohort tier, annual rate in bps, term days, max amount in USD cents, validity window) in plain language. However, it omits lenderId (though implied by 'on behalf of an authorised lender') and agentBearer, leaving slight gaps. Still, it adds substantial meaning beyond the raw 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's purpose: 'Submit a draft credit-quote on behalf of an authorised lender.' It uses a specific verb and resource, and the phrase 'on behalf of an authorised lender' distinguishes it from read-only sibling tools like get_lender_history or verify_lender. The listed fields reinforce the distinct write operation for creating credit quotes.

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 for when to use the tool: when an authorised lender needs to submit a credit quote. It does not explicitly name alternatives or exclusions, but the uniqueness of the action and the scaffolded notice ('not yet shipped... degrades to { ok: false, scaffolded: true }') give practical usage guidance. The context is clear, though not fully exhaustive regarding 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?

The description goes far beyond annotations by disclosing the atomic concurrency guarantee ('two concurrent agent sessions cannot double-allocate the last unit'), the hold TTL defaults and cap ('Default hold TTL 900s (15min), hard cap 3600s (1h)'), and the specific failure reasons (OUT_OF_STOCK, NOT_DELIVERABLE, HOLD_SERVICE_UNAVAILABLE). This adds rich behavioral context that the annotations (readOnlyHint=false, openWorldHint=true) do not provide.

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 dense but every sentence earns its place: core action, workflow context, concurrency rationale, return shape, failure reasons, hint guidance, and TTL policies. It fronts the primary purpose and then layers details logically without redundant wording.

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 complexity (atomic hold, multiple params, no output schema), the description covers return values on success and failure, the exact failure reason enum, the workflow sequence, and TTL semantics. The only missing piece is a few parameter semantics, but those are partially handled by the schema and the description still provides enough context for correct invocation in the main loop.

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 has 0% description coverage, so the description must compensate. It adds meaning for deliverTo ('estimates shipping + tax for deliverTo'), productIdHint/shopIdHint (for resolution), and holdTtlSec (via TTL defaults). However, it does not explain skuId, quantity, agentBearer, or consumerAgentKind, leaving those to the schema's minimal type info. This is a partial compensation, not a full one.

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 function: 'Atomically quote price + delivery + reserve stock for a SKU'. It uses a specific verb and resource, and explicitly differentiates itself from siblings by calling it 'the linchpin between discovery (find_inventory) and tender (start_checkout)', making its unique role 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?

It provides explicit usage context by positioning the tool within the consumer-agent loop and tells the agent to pass 'productIdHint + shopIdHint from a preceding find_inventory result'. This gives clear when-to-use guidance and references the exact preceding tool, while also implying the next step (start_checkout).

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 mark this as readOnly and idempotent, so the description adds valuable behavioral context beyond that: it explains the sort order (by issuedAttestationCount and lastAttestationAt), the computed recommendation score, and graceful degradation to an empty array on backend errors. This is useful transparency for an agent deciding whether to rely on the result.

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 three sentences long, front-loaded with the core purpose, and every sentence adds value: return format, usage scenario, and parameter details. 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 simple optional-parameter read tool with no output schema, the description is complete. It covers purpose, when to use, all parameters with defaults, return sorting, and error behavior. 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 schema has 0% description coverage, so the description carries the full burden of explaining parameters. It does so thoroughly: jurisdiction defaults to GLOBAL, archetype enum values are listed, limit range is given (1-100, default 10), and the meaning of each filter is implied. This fully compensates for the schema's lack of 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's function: 'Get an ordered list of recommended lenders for a merchant based on jurisdiction and archetype.' This is a specific verb ('Get') and resource ('lenders') that distinguishes it from sibling tools like verify_lender or get_lender_history.

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 explicit usage context: 'Use this when an agent needs to suggest lenders to a merchant based on geographic + regulatory constraints' with a concrete example. It doesn't explicitly mention when not to use it or alternative tools, but the contextual guidance is clear enough for a 4.

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, covering safety. The description adds valuable behavioral context beyond annotations: it states the result is sorted by track record (successfulIngestionCount, lastIngestionAt) with a computed recommendation score, and that it degrades to an empty array on backend error. This goes beyond the structured 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 compact at four sentences, each earning its place: purpose, return characteristics, usage guide, and parameter/behavior details. It is front-loaded with the core purpose and avoids redundant or fluffy language.

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 two optional params and no output schema, the description covers purpose, usage, parameters, and error behavior. However, it does not explain how the merchant is identified (no merchant parameter in schema), which could be ambiguous. Still, the overall coverage is strong for the complexity level.

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%, so the description must compensate. It does so by naming both optional filters, listing the archetype enum values (stord, flexport, shipbob, generic), specifying the limit range (1-100), and adding the default limit of 10. This fully clarifies parameter meaning beyond the raw 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 'Get an ordered list of recommended service providers (WMS, 3PL, fulfillment partners) for a merchant.' This uses a specific verb ('Get'), identifies the resource ('service providers'), and scopes it to merchant needs. It also distinguishes from sibling tools like recommend_lender by explicitly naming WMS/3PL/fulfillment partners.

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 when-to-use context: 'Use this when an agent needs to route a merchant to an appropriate WMS/3PL based on operational capability.' It gives a concrete example. However, it does not explicitly mention when not to use it or alternative tools, so it lacks the full when/when-not/alternatives structure for a 5.

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

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

This is an annotation contradiction. The description states 'Idempotent on (quoteId, occurredAtIso)' while the annotations set idempotentHint to false. This is a serious inconsistency that could mislead an agent into believing duplicate calls are safe when they may not be. Although the description discloses the scaffolded state and degraded response, the contradiction earns a score of 1.

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 information-dense and front-loaded with the core purpose, followed by backend behavior, idempotency, and scaffolding status. Each sentence adds value, though the scaffolded notice with ticket numbers is a bit lengthy. Overall it is well-structured and concise for the amount of context provided.

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 discloses the scaffolded state and the degraded response, and notes that the backend is being tracked. However, it does not describe the success response format, what happens when cumulative settlement crosses the threshold (exact threshold or attestation details), or authentication requirements (agentBearer). With no output schema, the description should have provided more guidance on expected outcomes and side effects.

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%, so the description must compensate for parameter meaning. It explains eventType (via the PAID/PARTIAL/MISSED enum) and mentions quoteId and occurredAtIso in the idempotency note, but does not elaborate on lenderId, merchantId, amountUsdCents, evidence, or agentBearer. This is a partial aid but insufficient for a 8-parameter tool with no 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 uses a specific verb ('Record a repayment event') and clearly identifies the resource (previously-issued credit quote) and the event types (PAID/PARTIAL/MISSED). It distinguishes itself from the sibling verify_repayment_history by positioning this as the writer vs. reader tool.

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 (recording repayment events) and mentions its relationship to quote_credit_terms (companion) and verify_repayment_history (sibling reader). It does not explicitly state 'when not to use' or list alternatives, but the context is clear enough to prevent confusion with the read-only verification 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?

Adds substantial behavioral context beyond the annotations: the async operator approval process, the on-chain mint trigger, the return payload (requestId + PENDING status), and the conditional idempotency. These details are not present in the annotations and enable the agent to understand state transitions and 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?

Three dense, well-structured sentences each provide distinct value: purpose, workflow + return value, and idempotency caveat. There is no redundancy or fluff; every sentence earns its place.

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

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

The description covers the core action, asynchronous review, return payload, and resubmission behavior. Gaps remain: the notes parameter's purpose is unspecified, and details like the pending window duration or rejection behavior are absent. Still, it is strong for a tool with no output schema and only two parameters.

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 description enriches shopSlug semantics by explaining its role in idempotency and identifying the target shop. However, the notes parameter is completely unmentioned, and with 0% schema description coverage, the description does not fully compensate 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 states the specific action ('Submit a brand attestation request'), the resource ('for a droplinked shop'), and the downstream effect ('Operator reviews + approves → triggers Schema A on-chain mint'). It clearly distinguishes this tool from siblings like get_brand_attestation_status and verify_brand_attestation by indicating it initiates the process.

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: the operator review workflow and idempotent resubmission behavior (re-submitting for the same shopSlug within the pending window returns the existing requestId). However, it does not explicitly mention alternatives or when not to use this tool, relying on sibling tool names for that differentiation.

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 substantial behavioral context beyond annotations: it discloses the auth requirement ('Authorization: Bearer ... via the two-header model'), specifies that the MCP layer does not decide routing, clarifies idempotency behavior, and outlines the return value (resolved tier, selected partner for Tier-1). This goes well beyond the minimal hints in 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 four sentences, each adding value: purpose, routing behavior, return value, and auth/idempotency. It is front-loaded with the primary verb and resource, and there is no fluff or repetition.

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

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

Given the tool's moderate complexity and lack of output schema, the description covers the key aspects: what it does, how routing works, return value, and auth. It falls short of full completeness by not explaining the 'two-header model' or potential error/failure scenarios, but it is sufficient for an agent to invoke the tool correctly in most cases.

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?

With 0% schema description coverage, the description needed to explain both parameters. It indirectly suggests agentBearer is the JWT via the auth mention, but it never explicitly maps agentBearer to the header or explains the 'two-header model'. applicationId is only implied by the overall purpose. This is insufficient compensation for the schema's lack of 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 action ('Trigger a Tier-1 / Tier-2 / Tier-3 lending application submission') and identifies the specific backend service (TierRoutingService). It distinguishes this tool from read-only siblings like get_lending_application_status by focusing on submission, and the tier/routing details add 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?

The description provides clear context for when to use the tool (to submit a lending application) and includes important usage constraints (backend decides routing, idempotent re-submit on SUBMITTED state, required auth). However, it does not explicitly name alternative tools for status checking or other actions, so it lacks 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the paginated return format, the parallel verifications array with its fields (brand_verified, kyb_tier, etc.), and the underlying MoR + KYB cascade that supports the badge. This adds meaningful behavioral context not present in 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 three sentences, each earning its place: the first states the action and result type, the second details the verification array, and the third gives practical usage guidance. It is front-loaded and free of fluff.

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

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

Given a simple two-parameter tool with no output schema, the description covers the return payload (product summaries and verifications), the verification fields, and recommendation guidance. It slightly omits pagination mechanics (e.g., how to page through results), but overall it is adequately 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 0%, so the description must compensate. It explains 'query' as free-text and mentions pagination, but limit's behavior (e.g., max results, defaults) is only in the schema's default/max fields. The description provides context for query but not detailed semantics for limit.

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 'Search the public droplinked catalog by free-text query', clearly stating the action (search), resource (public droplinked catalog), and query type (free-text). This distinguishes it from sibling tools like get_product (specific product lookup) and list_shop_products (shop-scoped listing).

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—any free-text search against the catalog—and adds guidance to prefer verified merchants when citing recommendations. It does not explicitly state when not to use it or name alternative tools, 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.

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

Annotations indicate this is a write operation (readOnlyHint=false) and not idempotent, and the description honestly discloses the side effect of minting a cart. It adds transparency about the two return modes and the Stripe.js flow. 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?

Two sentences, front-loaded with the action and return types. Every clause adds value, with no redundant or vague phrasing. Excellent conciseness for a tool with moderate 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?

The description covers the essential flow, side effects, and return values, which is enough for an agent to invoke the tool correctly in most cases. However, it omits details about buyer object requirements and other parameters, and has no output schema to fill the gap. Slightly more explanation would make it 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 0%, so the description must carry the burden of explaining parameters. It only clarifies the 'mode' parameter and mentions SKU, but leaves shopId, quantity, buyer object fields, returnUrl, and paymentMethod unexplained. The agent must infer their purpose from names alone.

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 ('Begin') and resource ('droplinked checkout for a SKU'), immediately clarifying the tool's function. It clearly distinguishes from siblings by focusing on initiating checkout rather than managing cart lines or processing payments, and it explains the two output modes.

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

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

The description gives clear context: use this tool to start an agent-initiated checkout, then confirm payment via Stripe.js in managed mode. It does not explicitly state when _not_ to use it (e.g., for adding items to cart or finalizing payment), but the mode explanation provides practical usage 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?

Beyond the annotations (readOnly/openWorld/idempotent), the description discloses graceful degradation to verified=false on backend error or missing brand, and promises a stable response shape. This is valuable behavioral context that annotations alone don't provide.

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 dense but each sentence serves a purpose: function, usage, error behavior, and role. It stays concise despite covering multiple aspects, with critical info 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?

With no output schema, the description provides the exact return shape and names all fields. It covers the normal path, failure mode, and integration point, making it self-sufficient for a 1-parameter tool.

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

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

The input schema only defines brandSlug with a regex pattern; the description clarifies it is the 'single shop slug' and ties it to the attestationUid round-trip from find_inventory. This adds domain meaning to an otherwise raw identifier.

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: 'Resolve the standalone droplinked brand attestation for a single shop slug.' This clearly distinguishes it as a read/verification operation scoped to one brand, distinct from cross/request/status siblings.

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... before proceeding to checkout.' Also notes the agent's role as the verification UX, giving strategic context. It does not explicitly name alternatives, but the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context by stating the tool 'Gracefully degrades to verified=false on missing attestation / backend error' and that 'the response shape is stable so the agent can always cite credit-trust state.' This goes beyond the annotations and helps the agent anticipate failure modes.

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

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

The description is well-structured and front-loaded: purpose first, then return shape, then usage guidance, then behavior on error. Every sentence adds value, with no repetitive or filler content. It is concise yet information-dense.

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 output schema, the description comprehensively lists the return fields and explains the stable response shape even on failures. It also covers usage context and the effect of lenderId. It could be slightly more complete by describing the meaning of key fields like creditTier or ratePercent, but the field names are self-explanatory and the core behavioral aspects are 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?

Schema description coverage is 0%—neither parameter has an explicit schema description. The description clarifies that lenderId is optional and used to scope to a specific lender, and merchantId is the identifier for the merchant (implied). This adds some meaning, but it does not explain formats, patterns, or required semantics beyond what the schema property names already convey, so it only partially compensates for the lack of 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 states a specific verb ('Resolve') and resource ('active EAS credit-risk attestation (Schema B)') for a merchant, and clearly distinguishes it from sibling verify_* tools (brand, cross, lender, methodology, repayment) by focusing on credit risk. It also enumerates the return fields, making the tool's 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 explicitly says when to use it: 'as the trust handshake before a buyer-agent extends credit-aware BNPL terms at checkout, or when a lender-agent reads its own previously-issued attestation.' It also provides guidance on using lenderId to scope to a specific lender. It does not explicitly list alternatives to avoid, but the context is clear enough to prevent misuse.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: it describes the return structure (per-row breakdown plus summary with count, avgTrustScore, and issuer types) and the graceful degradation to an empty envelope on missing data, which is not evident from 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 front-loaded with the main purpose and contains four sentences, each serving a distinct role: core function, mode differentiation, return value, and usage context. It is concise without being terse, though it could tighten the use-case sentence slightly.

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

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

The description covers the tool's purpose, modes, return value, graceful degradation, and typical use cases. Since there is no output schema, the description's mention of the summary fields (count, avgTrustScore, issuer types) is helpful. Missing 'limit' semantics is a minor gap, but overall the description is sufficiently complete for a read-only query 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 0%, so the description must compensate. It explains the 'mode' parameter thoroughly (subject = ABOUT this entity, issuer = BY this entity) and implies 'rootUid' is the entity identifier via context. However, it does not explain the 'limit' parameter's meaning or behavior, leaving a notable gap.

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 tool's function with a specific verb and resource: 'Resolve EAS Schema D (cross-attestation) peer-trust rows for a given entity.' The two modes (subject/issuer) further differentiate it from sibling verification tools by explaining both the incoming and outgoing attestation perspectives.

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 usage context: 'Use this in trust-graph composition flows' and gives concrete examples such as 'buyer-agent verifying a merchant has lender testimonials, lender-agent reading peer signals.' However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

The description discloses graceful degradation to found=false on missing lender/backend error and notes the stable response shape. This goes beyond the readOnlyHint and openWorldHint annotations, providing actionable behavioral detail without 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?

Two sentences, front-loaded with the primary purpose, followed by a use-case and behavior note. Every clause earns its place with 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?

The tool is simple (1 param, no output schema), but the description covers the return shape, error behavior, and practical usage context. Combined with annotations (readOnly, openWorld, idempotent), the description fully equips an agent to invoke and interpret the tool without 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 has 0% description coverage, but the parameter lenderId is simple. The description adds meaning by explaining that lenderId is used to resolve the profile and is also part of the return shape, plus implies it can be missing. It doesn't elaborate on format beyond the schema's pattern, but the context is sufficient.

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 'Resolve the public profile for a lender by lenderId' with a specific verb, resource, and identifier. It lists the exact return fields, which distinguishes it from sibling tools like get_lender_history and verify_credit_risk.

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 says 'Use this to round-trip a Schema B credit-risk attestation's lenderId field...' giving a precise scenario and cross-check purpose. It does not mention alternatives or when not to use, but the targeted use case is clear enough.

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

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

With annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral context beyond them: it reveals possible statuses (ACTIVE, SUPERSEDED, REVOKED), the exact return envelope fields, and a 'graceful clean-slate envelope on missing / backend error.' This gives the agent insight into edge-case behavior that annotations do not cover, and it contradicts nothing.

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 dense but tightly organized: purpose → conditional behavior → return fields → workflow → complementary tools → error handling. Every sentence earns its place; there is no fluff or repetition of schema details. The structure front-loads the primary purpose and then logically builds to advanced usage.

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 there is no output schema, the description compensates by enumerating the return fields and statuses. It also covers both invocation patterns, the error envelope, and references the on-chain Schema B payload, which is essential context for a forensic workflow. This is a complete description for a tool with moderate complexity.

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 has 0% description coverage, so the description must carry the full burden. It does so by explaining that lenderId identifies the lender and that methodologyHash, when provided, selects a specific version; when omitted, the active version is returned. This adds significant semantic meaning beyond the raw schema properties.

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 specific verb and resource: 'Look up a lender's underwriting methodology by lenderId.' It clearly distinguishes two modes (with and without methodologyHash) and lists the return fields, making the tool's function unmistakable. Unlike sibling tools like get_methodology_versions or verify_lender, this focuses on a single methodology lookup, which is explicitly differentiated.

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 guidance is explicit: it explains when to omit methodologyHash (to get the current active methodology) and when to include it (to retrieve a specific version cited on an attestation). It also provides a forensic workflow with concrete steps, and names complementary tools (verify_lender, verify_credit_risk) for the full chain, giving clear context for when this tool is appropriate.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the graceful degradation to verified=false on missing data and details the exact return fields (aggregated counters plus per-lender breakdown). This adds meaningful behavioral 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 three sentences: purpose, usage guidance, and a behavioral note. Each sentence adds value with no redundancy or filler material.

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 having no output schema, the description lists the exact return fields, explains the degradation behavior, and provides usage context. For a simple one-parameter read-only tool with strong annotations, this is comprehensive.

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 has no description for merchantId (0% coverage), but the tool name and description make it obvious that merchantId identifies the merchant. The description doesn't explicitly define the parameter, but the context is sufficient for a single, self-explanatory parameter with a pattern defined in the schema.

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

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

The description opens with a specific verb ('Resolve') and resource ('merchant's repayment-history rollup'), explicitly scoping to EAS Schema C attestations. It clearly distinguishes from sibling tools by noting the cross-lender aggregation and explicitly contrasting with verify_credit_risk.

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 explicit when-to-use guidance ('when a buyer-agent / cohort engine / underwriter needs a quick read') and an explicit alternative ('For lender-agent self-queries use verify_credit_risk with a lenderId filter instead'). This provides clear context and exclusion.

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