droplinked

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

Beyond the annotations, the description discloses the exact return shape ({ status, cartId, lineCount }), the failure enum with values, the runtime auth failure mode (JSON-RPC -32001, never reaches the tool), and the credentialing contact. This gives an agent concrete expectations of side effects and error handling.

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

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

The text is longer than typical, but every component earns its place: purpose, usage, dependency, return, failures, and auth. Key information is front-loaded and the AUTH section is cleanly separated.

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 mutation tool with no output schema, the description is unusually complete: it covers how to get the cart ID, what the response contains, the main failure reasons, and the auth prerequisite. Only the optional referrer parameter is left unexplained, which is minor against the rest.

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 most parameter meaning. It explains cartId through its source, skuId as the product variant, and quantity as the line amount. However, the optional referrer parameter is never mentioned, leaving its semantics undocumented.

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: 'Add a product variant (skuId) and quantity to an existing droplinked cart.' It clearly names the targeted entity and distinguishes this from sibling tools like cart.removeLine and cart.updateLineQuantity by framing it as incremental cart building.

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?

'Use this to build a multi-item cart incrementally before checking out' states the intended use context, and the cartId provenance from start_checkout or a prior cart.addLine call gives the ordering prerequisite. It does not explicitly exclude alternatives (e.g., pointing to cart.updateLineQuantity for quantity changes), so it stops short of full when-not guidance.

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

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

Annotations already establish the tool as non-read-only, idempotent, and non-destructive. The description adds substantial context beyond these: the return shape including minor-unit discountAmount, the auth requirement (not on public read tier, specific error code MCP_API_KEY_REQUIRED), and the full set of structured error reasons. This goes well 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 long (two paragraphs) but every sentence provides actionable information: purpose, return type, workflow position, error handling, and auth. It is front-loaded with the purpose and outcome. The auth paragraph could be seen as auxiliary, but it is critical for correct invocation. Overall it is dense and structured, though slightly verbose.

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 an operation with no output schema, the description covers return structure, error codes, workflow placement, and auth. It does not describe side effects beyond 'apply' or whether the cart is permanently modified, but the idempotentHint and error handling suggest retry safety. Given the tool's complexity and lack of structured output, this is very 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 clarifies that discountCode is a 'coupon code' and that discountAmount comes back in minor units, but it does not explicitly define cartId (though it is implicitly the droplinked cart from addLine) or give syntax/format details for either parameter. The description adds some meaning but not exhaustive parameter 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 opens with a specific verb and resource: 'Apply a discount or coupon code to a droplinked cart.' It clearly distinguishes this tool from siblings because no other tool in the list handles discount application, and it names the workflow context (after addLine, before checkout/payment). The purpose is unambiguous and 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?

Explicitly states the positional ordering: 'Call this after cart.addLine and before start_checkout / process_payment.' Also provides guidance on error handling and retry strategy: 'so the orchestrating agent can retry with a different code or proceed without a discount.' No alternative tool is suggested, but the sequencing and fallback behavior are clearly documented.

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, the description discloses the exact return shape (`{ status, cartId, skuId, remainingLineCount }`), the structured error reasons (CART_NOT_FOUND / LINE_NOT_FOUND / BACKEND_BAD_REQUEST / BACKEND_UNAVAILABLE), and the authentication failure behavior with error code -32001 and data.code=MCP_API_KEY_REQUIRED. These are meaningful behavioral details not inferable from readOnlyHint, destructiveHint, or idempotentHint alone.

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

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

The description is well-structured with a leading one-sentence purpose, a return contract, an alternative routing, error semantics, and an auth note. Every section adds actionable information and the structure is front-loaded so the most essential facts appear first. No filler 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?

For a two-parameter mutation tool with no output schema, the description covers the key operational needs: what action is performed, what the response looks like, how failures are surfaced, how this tool differs from its closest sibling, and what authentication is required. An agent has enough to invoke it correctly and handle outcomes.

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 carries the burden of explaining both parameters. It clarifies that skuId identifies the line to delete, but never explains cartId's role or how to obtain/format either value beyond what the schema's names and minLengths already imply. This is a notable gap for an otherwise thorough description.

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: 'Remove a product line from a droplinked cart by skuId.' It immediately clarifies the granularity (line-level removal via skuId) and distinguishes itself from the sibling cart.updateLineQuantity for quantity changes. This leaves 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 explicitly states when not to use this tool: 'To change quantity (not remove entirely) use cart.updateLineQuantity instead.' It names the alternative sibling directly and gives the condition that selects it. Auth expectations are also clearly scoped, so an agent knows the operational context before calling.

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 cover read-only/idempotent/destructive hints, so the description adds meaningful context: the exact return shape, structured error reasons, and the precise auth failure mode with error code -32001. This goes well beyond the structured metadata.

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

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

The description is front-loaded with the core action, then return value, then alternative, then error handling, then auth. Every sentence adds operational value with no filler or repetition of the schema.

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 mutation tool with no output schema, the description is complete: it gives the return shape, structured error reasons, authentication requirements, and the key usage rule about removal. An agent has enough to invoke it correctly and handle failures deterministically.

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 carries the burden. It explains that skuId is the variant id used when the line was added and clarifies that quantity=0 is not the removal mechanism. cartId is left self-evident, but the critical disambiguation is provided.

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

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

The description states a specific verb and resource ('Change the quantity of an existing line in a droplinked cart'), clarifies the identifying parameter (skuId), and explicitly contrasts with cart.removeLine. This distinguishes it clearly from sibling cart tools like cart.addLine and cart.removeLine.

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 tells the agent when to use an alternative: 'Use cart.removeLine to remove a line entirely instead of setting quantity=0.' It also specifies the authentication precondition and which calls require credentials, giving clear operational context.

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 readOnly, idempotent, and open-world hints, and the description adds substantial behavioral context beyond those: backend clamping of `limit`, the meaning of `verifiedBrand=false`, the absence of a country filter, the global scope of every card, and the representation of the cheapest purchasable variant. No contradiction exists.

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: primary behavior, required inputs, optional filters, global-scope caveat, return shape, and ranking guidance. It is front-loaded with the core discovery behavior and then efficiently covers each important semantic nuance.

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 9-parameter tool with no output schema and no parameter descriptions, the definition is exceptionally complete: it covers required input combinations, filter semantics, return fields, cardinality, global behavior, and sizing limits. An agent has everything needed to invoke this tool correctly and interpret its results.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning, and it delivers. It explains `query`, `brandSlug`, `currency`, `minPrice`, `maxPrice`, `verifiedBrand`, `inStockOnly`, `source` with enum values, and `limit` — including the critical clamp behavior that contradicts the schema's maximum of 50.

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 ('Discover') and a specific resource: droplinked inventory, with one card per product and a defined set of catalog sources. It clearly distinguishes the tool's scope from siblings like search_products or list_shop_products by emphasizing cross-source inventory discovery rather than general product search or per-shop 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 gives clear invocation guidance: at least one of `query` or `brandSlug` is required, optional filters are enumerated, and notable limitations are stated (no country filter, `verifiedBrand=false` is not 'unverified only', `limit` clamps at 25). It stops short of explicitly naming sibling alternatives or stating when to prefer another tool such as search_products or find_merchant.

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, idempotentHint, and openWorldHint=false; the description adds valuable behavior beyond that: category is a product-title fan-in, matchedProducts distinguishes a true zero from a broken lookup, empty results never widen to all merchants, and verifiedBrand is backed by a KYB cascade. No contradiction with annotations.

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

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

The description is dense but well-organized: action and modes first, then mode-specific semantics, return shape, category edge behavior, empty-result behavior, and usage guidance. Every sentence carries distinct information and there is 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?

With no output schema, the description provides the return shape and important edge cases. It covers all four parameters, the exactly-one constraint, empty-result behavior, and verified-merchant guidance, making it complete enough for an agent to call 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?

Schema description coverage is 0%, and the description compensates fully: slug is an exact storefront URL, name is a case-insensitive substring over merchant names, category is a case-insensitive substring over product titles deduped to merchants, and limit caps the returned cards. It adds substantial meaning beyond the raw schema fields.

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 (find), a specific resource (droplinked merchant), and the three lookup modes: slug, name, and category. It also clearly distinguishes category matching from a normal taxonomy lookup by explaining the product-title fan-in behavior, which differentiates it from related find_* and search_* 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?

The description clearly instructs the agent to provide exactly one lookup key and explains each mode's matching semantics, plus the empty-result behavior. However, it does not explicitly name alternative sibling tools or state when-not-to-use this tool, so it stops short of full alternative routing.

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 declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds substantial operational behavior beyond that: the 1-based pagination contract with explicit response fields, the no-cursor rule, the shop_verification block's per-merchant semantics (KYB shared across the page), and a mandatory user-facing instruction to surface verification status. Nothing contradicts the annotations.

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

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

Four tight sentences, each earning its place: purpose, pagination contract, verification-block semantics, and an actionable user-facing directive. The core purpose is front-loaded and there is zero 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?

Without an output schema, the description carries the burden of explaining the response, and it does: pagination fields, page-level verification sharing, and the parallel verifications array are all specified. For a read-only list route of modest complexity, an agent has everything needed to call it correctly and represent the results to the user.

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 shopSlug ('by slug'), the 1-based page counting, and the absence of a cursor — which clarifies how page and nextPage relate. The limit parameter is left to the schema's default/max, but its meaning is easily inferable from the pagination 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 opening sentence names a specific verb ('Page through'), a precise resource ('public catalog of a single droplinked shop'), and the key identifier ('by slug'). This cleanly separates it from siblings like search_products (cross-shop search), get_product (single product), and get_feed (aggregated feed) without needing to open any schema.

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

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

The scope — 'public catalog of a single droplinked shop' — states clear context for when this tool applies versus the search and verification siblings. However, it never explicitly names an alternative (e.g., search_products for cross-shop discovery) or states a when-not-to-use condition, 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?

Annotations signal a write operation (readOnlyHint=false) and non-destructive behavior, and the description adds substantial behavioral detail beyond those hints: idempotency keyed on acpIntentId with replay=true, the shape/enum of finalization.status, and an auth note that the tool never executes without a valid X-MCP-API-Key. The scoped idempotency claim refines rather than flatly contradicts the general idempotentHint=false.

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 core purpose is front-loaded, and the status list and auth note are set off in compact blocks. It is longer than minimal because the tool is complex, but almost every sentence adds information and it does not repeat the schema.

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 mutating, authenticated tool with no output schema and five parameters, the description covers a lot: sequencing, statuses, idempotency, auth, and return envelope. However, it omits any explanation of agentBearer and consumerAgentKind and does not describe failure behavior beyond the generic status enum, so an agent cannot fully reason about all inputs.

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 parameter meaning. It clarifies acpIntentId (Stripe payment intent) and holdId (optional inventory hold), but leaves agentBearer and consumerAgentKind completely unexplained, and orderId only by inference from 'droplinked order.' With five parameters and zero schema coverage, this is only partial compensation.

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: 'Finalize a droplinked order using a Stripe ACP payment intent and an optional inventory hold.' It also places the tool in the pipeline (after find_inventory + quote_inventory_available + create_payment_intent) and names the return statuses, so an agent can distinguish it from cart, quote, and verification 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?

It gives an explicit call sequence: 'The consumer agent calls this after find_inventory + quote_inventory_available + Stripe ACP create_payment_intent' and says it 'Closes the agent-to-agent transaction loop.' It does not spell out when not to use alternatives, but the pipeline 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description goes far beyond that. It discloses that the backend persists the row, stamps a quoteId, and integrates with the marketplace funnel and attestation flow. It also openly states the scaffolded state—returning `{ ok: false, scaffolded: true }` until the backend lands—and precisely describes the auth failure mode (JSON-RPC error -32001, code MCP_API_KEY_REQUIRED, never reaching the tool). This level of disambiguation is exemplary and aligns with the annotations.

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

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

The description is longer than average but every section earns its place: purpose first, then parameter semantics, then behavioral details, then scaffold warning, then auth guidance. Front-loading the core action and listing inputs makes it scannable. The scaffold and auth notes are necessary given the tool's incomplete backend and security requirements. It is dense but not redundant.

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

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

For a complex write tool with auth, scaffold status, and 7 parameters, the description covers the essentials: what it does, what inputs to provide, what happens on success (persists, gets quoteId), what happens on failure (scaffold or auth error), and who can use it. It does not specify the exact success response format beyond quoteId, nor elaborate on idempotency or the attestation flow details, but these are minor gaps relative to the rich context provided. The annotations and schema fill remaining structured 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 is the only semantic source for parameters. It maps most parameters: 'cohort tier (AAA..CCC|NR)' to cohortTier, 'annual rate in basis points' to annualRateBps, 'term length in days' to termDays, 'maximum facility size in USD cents' to maxAmountUsdCents, and 'validity window' to validUntilIso. It also implies lenderId via 'authorised lender.' However, it omits agentBearer entirely and does not elaborate on format of validUntilIso beyond the name. This is substantial but not fully exhaustive.

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: 'Submit a draft credit-quote on behalf of an authorised lender.' It then enumerates the exact data captured (cohort tier, rate, term, amount, validity window), making the tool's function unambiguous. It distinguishes itself from read-only siblings by explicitly stating this is a write operation that persists data, and the auth section reinforces that it is not a public read. The scaffold caveat further clarifies its current 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 provides clear context: it is a write operation for authorised lenders, requiring a valid API key, and it is not on the public read tier. The scaffold warning tells the agent when it may fail and what to expect. However, it does not explicitly name alternative tools or state 'use this instead of X for Y'—it relies on the contrast between read and write operations and the auth requirement to imply usage boundaries. This is slightly above average but not fully explicit.

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

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

Goes well beyond annotations by disclosing the atomic-hold behavior that prevents double allocation, the exact success/failure return envelope, the failure reason enum, the API-key auth failure mode, and default/hard TTL limits. This is consistent with readOnlyHint=false and idempotentHint=false.

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?

Every sentence earns its place: function first, then pipeline mechanics, return contract, parameter hints, TTL policy, and auth requirements. It is dense but well-organized, with the most important facts front-loaded.

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

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

For a high-complexity, 8-parameter tool with no output schema, it covers auth, return shape, failure reasons, concurrency behavior, TTL policy, and hint usage. The only gaps are the two optional credential/context parameters (agentBearer, consumerAgentKind) and no explicit statement of quantity semantics, so it is nearly complete but not exhaustive.

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 carries the burden and explains deliverTo (shipping/tax), productIdHint/shopIdHint (from find_inventory), and holdTtlSec (900s default, 3600s cap). However, agentBearer and consumerAgentKind are not explained, and skuId/quantity are only implied by the SKU/reserve wording.

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 precise verb-object pair: 'Atomically quote price + delivery + reserve stock for a SKU on droplinked', and situates the tool in the agent loop between find_inventory and start_checkout. This clearly distinguishes it from the many related commerce tools without needing to inspect 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?

It gives clear placement in the consumer-agent pipeline (after find_inventory, before start_checkout) and instructs the caller to pass productIdHint + shopIdHint from a preceding find_inventory result. It also warns that this tool is not on the public read tier, unlike discovery/catalogue reads, though it does not explicitly name alternative tools for other scenarios.

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 readOnly/idempotent/openWorld annotations, it discloses the counterparty-privacy policy, the lack of any lender-name field, the 'global-fallback' vs 'exact-jurisdiction' match kinds, and graceful degradation to an empty array on backend error. This is rich, non-obvious behavioral context that an agent needs to avoid hallucinating lender names.

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

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

The description is front-loaded with the core purpose, then adds return-shape details, usage context, a critical prohibition, parameter summary, and error behavior. Every sentence earns its place, including the policy warning that prevents hallucinated lender names.

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 supplies the return contract: an ordered array with jurisdiction, matchKind, and rank. It also documents defaults, acceptable filter values, and backend-error degradation. An agent has enough information to invoke the tool correctly and interpret its results 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?

Schema description coverage is 0%, so the description carries full responsibility for parameters. It explicitly documents jurisdiction (defaults to GLOBAL) and limit (1-100, default 10), adding a default that is absent from the schema and clarifying each parameter's role in filtering results.

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 purpose: determining whether droplinked can source financing for a merchant's jurisdiction and how matches rank. It clearly differentiates itself from lender-identity tools like verify_lender by explicitly stating it does NOT identify lenders, so an agent can discriminate between 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?

The description gives an explicit when-to-use scenario: 'Use this when an agent needs to tell a merchant whether financing is reachable where they operate.' It also provides a clear when-not-to: do not tell the user which lender matched, because identity is withheld. It does not name an alternative tool for lender identity, 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 readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds meaningful behavioral details: results are sorted by track record, only ACTIVE providers are returned so no per-row status check is needed, and the tool gracefully degrades to an empty array on backend error. This is exactly the kind of behavior an agent needs to know before relying 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 information-dense with no filler. It front-loads the core purpose, then covers return shape, sorting, use case, filters, and error behavior in a logical order. Every sentence contributes to successful invocation or interpretation of results.

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 read-only tool with two optional parameters and no output schema, the description is complete: it specifies returned fields, ordering, filtering options, defaults, active-only semantics, and failure behavior. No critical operational detail is missing.

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

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

Schema description coverage is 0%, but the description compensates by naming both optional parameters and their key semantics: archetype enum values and limit's 1-100 range plus default of 10. It could go deeper on the meaning of each archetype, but the enum values are self-explanatory and the added default value is genuinely useful beyond the schema.

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

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

The description states a specific verb ('Get'), a clear resource ('ordered list of ACTIVE service providers'), and the domain context ('WMS, 3PL, fulfillment partners'). It differentiates itself from sibling tools like recommend_lender by tying the tool to routing inventory ingestion or fulfillment, so an agent can immediately tell what it is for.

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: route a merchant to an appropriate WMS/3PL based on operational capability, with a concrete example ('which STORD-like provider should handle this?'). It does not explicitly name alternatives or when-not-to-use conditions, but the context is clear 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?

The description says 'Idempotent on (quoteId, occurredAtIso)' while the annotation idempotentHint=false — a direct contradiction. Per the rubric, this forces a score of 1 even though the description otherwise discloses scaffolding status and auth failure mode.

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

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

Front-loaded with the core operation; the idempotency, scaffolding, and auth details are all decision-relevant. The text is longer than average, but each section carries operational payload; minor issue numbers and the read-tier note are near misses but not padding.

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

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

Coverage of lifecycle, idempotency, scaffold state, and auth is strong for a no-output-schema tool, and the degraded response is shown. However, the successful response shape is never disclosed, and several parameters remain unexplained. An agent can call it but cannot fully predict the success/error contract beyond auth and scaffolding.

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 burden falls on the description. It names the eventType enum and identifies (quoteId, occurredAtIso) as the idempotency key, but gives no explanation of lenderId, merchantId, amountUsdCents, evidence, or agentBearer; agentBearer especially is left opaque. Only partial compensation for a six-required-parameter tool.

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

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

Opens with 'Record a repayment event (PAID / PARTIAL / MISSED) against a previously-issued credit quote' — a specific action, target, and value set. It clearly distinguishes itself from verify_repayment_history by describing itself as the Schema D writer and the sibling as the reader.

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 places the tool in its lifecycle: it is a writer that persists events and anchors attestations, while the sibling verify_repayment_history is the reader. The AUTH note draws a clear read/write boundary: write calls require a key, reads do not. It does not spell out an explicit 'use verify_repayment_history instead when...' exclusion, so it misses the top bar.

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 explicitly claims 'Idempotent: re-submitting for the same shopSlug within the pending window returns the existing requestId,' which directly contradicts the annotation idempotentHint: false. This is an annotation contradiction, so the score must be 1 even though the description does add useful auth and error 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?

Two tightly focused paragraphs. The first front-loads the core action, workflow, and return value; the second delivers essential auth requirements and error behavior. No filler sentences.

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?

Without an output schema, the description correctly states the return value (requestId + PENDING) and explains the auth error path in detail. It omits parameter meanings and sibling routing, but the core operation is well covered for a simple two-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?

Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It only references shopSlug indirectly in the idempotency note and never explains its pattern or meaning; notes is not mentioned at all. The description fails to add meaningful parameter 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?

States a specific verb and resource: 'Submit a brand attestation request for a droplinked shop.' It also clarifies the workflow (operator review + approval triggers on-chain mint) and the return value (requestId + PENDING), making it clearly distinct from status-checking and verification 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?

The description implies this tool is for creating an attestation request while get_brand_attestation_status would be for checking status, but it never explicitly states when to use this tool versus alternatives. It provides context around auth tiers but not usage exclusions.

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

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

The description is otherwise rich—backend-side tier resolution, no MCP routing decision, auth requirements, error code -32001, idempotent no-op on SUBMITTED state—but it directly contradicts the annotation idempotentHint=false by claiming 'Idempotent: re-submit on SUBMITTED state is a no-op.' Per the rubric, a contradiction with annotations 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 front-loaded with the core action, then adds routing behavior, return contents, idempotency, and auth/error details in a labeled AUTH section. Every sentence adds operational value and the structure makes the long context easy to scan.

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 mutation tool with no output schema and zero parameter coverage, the description covers a great deal: routing authority, auth model, specific JSON-RPC error, idempotency semantics, and partial return shape. The main gaps are exact parameter semantics and the full response structure, but the operational context is unusually 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, but it never explicitly defines applicationId or agentBearer. It hints at a merchant-or-operator JWT and an application cohort, but does not map those concepts to the two required parameters, leaving the agent to infer the parameter meanings.

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: 'Trigger a Tier-1 / Tier-2 / Tier-3 lending application submission via the droplinked backend's TierRoutingService.' This clearly distinguishes the tool from the many read/verify/quote siblings and states exactly what operation it performs.

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

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

The intended use is clear: call this when a lending application submission needs to be triggered. The auth note also clarifies that this is not a public read operation, and the final sentence explicitly contrasts it with credential-free discovery/catalogue/trust-fabric reads. It does not name specific sibling alternatives, but the context is strong enough to route 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?

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?

With annotations already carrying idempotentHint=false and destructiveHint=false, the description adds substantial value beyond them: it states the write behavior ('mints a cart'), discloses the concrete auth failure signature (JSON-RPC error -32001 with data.code=MCP_API_KEY_REQUIRED) and that the call 'never reaches the tool' without a key. This contextualizes real-world failure behavior that annotations cannot express. No contradiction with annotations — 'mints a cart' is consistent with readOnlyHint=false.

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 tight paragraphs with the core behavior front-loaded first and auth notes appended second. Every sentence earns its place, though the auth paragraph is slightly long-winded (three sentences covering the error, the key request path, and the read-tier contrast) and could be trimmed without losing signal.

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 high-complexity tool — 7 parameters, a nested buyer object, no output schema, and 0% schema descriptions — the description covers the output contract (hosted URL vs. client_secret) and auth, which is good since there's no output schema. But it leaves five parameters unexplained and gives no guidance on `returnUrl` or the buyer requirements. The half that is covered is strong; the parameter-semantics half is a clear gap.

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 bears the full burden of explaining parameters. It does explain `mode` thoroughly (hosted vs. managed semantics and default) and implies `skuId` via 'SKU'. But `shopId`, `quantity`, `buyer` (a nested object whose `email` is required), `returnUrl`, and `paymentMethod` receive no explanation, leaving an agent to guess their meaning from names alone. Partial compensation only.

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 precise verb-resource pairing ('Begin an agent-initiated droplinked checkout for a SKU') and immediately clarifies the mechanism ('Mints a cart on droplinked-backend') plus the two distinct return modes (hosted URL vs. Stripe client_secret). It even names the default behavior. This fully distinguishes it from cart.* editing tools and process_payment.

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

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

The description explains the hosted vs. managed mode distinction and clarifies the authentication context: it's not on the public read tier, returns a specific JSON-RPC error without a key, and contrasts with discovery/catalogue/trust-fabric reads that need no credential. It does not, however, explicitly route agents away from sibling tools such as process_payment or cart.addLine in a given scenario, which prevents 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 (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.