Brand Design Ltd.

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'No credentials needed.' It adds valuable behavioral context beyond the annotation: the integer minor-unit convention (100000 means 1000.00 EUR) and the explicit statement that no authentication is required. This is useful for an agent deciding whether to call this tool without setup.

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 short sentences, each carrying distinct information: what the catalogue contains, that no credentials are needed, and the integer minor-unit convention. No filler, no repetition of the schema, and the most important scoping information is 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 zero-parameter read-only tool, the description is nearly complete. It covers the resource, the data fields, the currency format, and the authentication requirement. The only minor gap is that it doesn't describe the exact response structure (e.g., whether it's a list or object), but with no output schema and a simple catalogue read, this is a small omission.

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 is trivially complete. The description adds meaning by explaining the return semantics (integer minor units, currency), which is the only parameter-like ambiguity an agent might face. With 0 params, the baseline is 4, and the description earns it by clarifying the data format.

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 ('Read') and resource ('service catalogue'), and enumerates exactly what the catalogue contains: names, prices, currency, and terms. This clearly distinguishes it from the sibling tools, which are all action-oriented (accept_offer, create_order, start_payment) or status-related (order_status, manifest).

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 implicitly signals when to use this tool: when an agent needs catalogue data (names, prices, currency, terms) before making decisions like creating an order or starting a payment. It doesn't explicitly name alternatives or exclusions, but the read-only nature and the sibling set make the usage context clear.

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

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

Annotations already mark this as non-read-only, non-idempotent and non-destructive, and the description adds substantial context beyond them: the auth requirement, that the caller must retain accessToken for follow-up calls, that the offer is hash-pinned, that some orders stall awaiting human pricing, and the MISSING_<field>/UNEXPECTED_FIELD error contract. The idempotencyKey explanation is consistent with idempotentHint=false (retries need a reused key) rather than contradicting it.

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?

Dense and front-loaded: purpose first, then return contract, then pricing edge case, then error codes. Every sentence carries information, though the back half is run-on and could be split for scanability.

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 correctly compensates by describing the return values (order id, offer, accessToken and its retention requirement). Combined with the error contract, idempotency guidance and human-pricing branch for an 8-parameter, nested-schema tool, it covers what an agent needs to call it 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 100%, so all eight parameters are already documented in the schema; baseline is 3. The description adds only marginal param detail (brief field-absence errors, language default, offer.terms.<language>.hash linkage), so it does not clearly exceed the structured data.

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+resource ('Place an order for a service') and immediately distinguishes it from siblings by describing the offer/accessToken handoff that feeds accept_offer. An agent can tell it apart from order_status, start_payment and accept_offer without opening a 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?

Gives clear sequencing context: credentials are needed (pointing to register_agent), the returned offer fields are what accept_offer consumes, and services with no catalogue price wait for a human. It does not state explicit when-not or compare against a sibling like accept_offer/order_status directly, but the workflow conditions are clear.

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

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

Annotations already disclose non-read-only, non-idempotent behavior, but the description adds crucial context: this replaces the previous challenge and clears its verification, requires domain control, and warns about not publishing secrets. These details go well beyond the annotations.

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

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

The description is dense but well-structured, front-loading the core action and sequencing. Each sentence adds distinct operational value, though slightly more compact phrasing could improve readability.

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

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

Covers the full workflow: issuance prerequisites, contact URL requirements, replacement behavior, next steps (publish TXT, then kya_verify), and security constraints. With no output schema, it sufficiently explains the expected return (txtValue at dnsName). Nothing an agent needs 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?

With 100% schema description coverage, the schema already explains parameters thoroughly, but the description adds practical guidance: contact is optional and reuses existing when omitted, and it is especially recommended on first OAuth connection. It also implicitly explains that secret and clientId are authentication alternatives.

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 (issue a fresh DNS TXT challenge) scoped to the authenticated agent identity. The description clearly distinguishes this from siblings like kya_verify and kya_status by naming them explicitly.

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?

Gives explicit prerequisites (commerce.order scope, OAuth, HTTPS contact URL on controlled domain), states the default when contact is omitted, and directly instructs to call kya_verify next. It also clearly excludes identity/spending implications, preventing 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=true and openWorldHint=false, and the description is consistent with them rather than repeating them. It adds genuinely new behavioral context: the OAuth scope required and what comes back (status plus DNS instructions and validity timestamps when present). It does not cover error behavior or what an unverified state returns.

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, auth prerequisite, return contract, and a non-mutation disclaimer. The core purpose is front-loaded in the first clause with no preamble.

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 read tool with no output schema, the description supplies the missing pieces: the OAuth scope needed to call it, the shape of the returned data, and confirmation that nothing is mutated. An agent has everything required to decide and 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 description coverage is 100% and both parameters (secret, clientId) are documented in-schema, including the Bearer header alternative. The description adds nothing about parameter form or precedence, which is acceptable given the schema does the heavy lifting, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read DNS domain-control verification') scoped to 'your currently authenticated agent', which is far more precise than a bare name restatement. It stops short of naming the sibling alternatives (kya_challenge, kya_verify) explicitly, so the contrast with them must be inferred from the resource name.

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?

Gives a clear precondition ('Needs commerce.read for OAuth') and a negative boundary ('does not change the contact, challenge or verification'), which tells the agent this is not the tool for mutating verification state. It never names which sibling to use instead when the agent wants to trigger a challenge or verify, so routing is only implied.

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, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds real behavioral context the annotations lack: the return fields verifiedAt/validUntil and the 24-hour validity window. It does not say what happens on a failed or repeated verification, so it falls short of a 5.

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?

Five short sentences, front-loaded with the operation, then prerequisites, then outcome and the authorization disclaimer. Every sentence carries distinct information; nothing is redundant with the schema or 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 usefully names verifiedAt and validUntil and the validity duration, and it states the prerequisite sequence and non-authorization boundary. It omits failure modes (e.g., what a TXT mismatch returns), which is the only remaining gap for a verification tool.

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

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

Schema description coverage is 100%, and both secret and clientId are thoroughly documented there, including the Authorization-header alternative. The description mentions authentication only obliquely ('currently authenticated agent') and adds no parameter detail, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Check the DNS TXT challenge ... and record domain-control verification' for the currently authenticated agent. It is clearly distinguishable from the sibling kya_challenge, which it names as the prerequisite step.

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 explicit prerequisites (OAuth scope commerce.order, and 'First call kya_challenge and publish its exact DNS TXT record') and an explicit boundary ('This does not authorize a purchase or a payment'). An agent knows the ordering and the scope of the operation without inference.

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 the description reinforces this with a read-oriented verb. It adds meaningful context beyond the annotation by stating 'No credentials needed,' clarifying authentication expectations and reducing the perceived need for setup.

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

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

Two short sentences with no filler. The core purpose and content scope are front-loaded, and the credential note is a useful standalone addition.

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 parameterless read-only tool, the description covers purpose, scope, and authentication expectations. Since there is no output schema, the enumerated content list effectively communicates what the agent can expect to learn from the manifest.

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 there is nothing for the description to explain. The baseline for a no-parameter tool is 4, and the description adequately conveys that no inputs are required.

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 the specific verb 'Read' with the resource 'commerce manifest' and enumerates the contained information: protocol, endpoints, authentication scheme, payment instrument, and limits. This clearly differentiates it from sibling action tools like create_order and start_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 gives clear context for when to use this tool: to obtain protocol, endpoint, authentication, and payment-limit details before taking action. It adds the practical note that no credentials are needed, which helps the agent decide it can be called without auth setup, though it does not explicitly contrast with alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read'. It adds the credential requirement ('Needs credentials') and the conditional invoice number behavior ('once one has been issued'), which are not in the annotations. This provides useful behavioral context beyond the schema.

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

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

Two concise sentences with no filler. The primary purpose is front-loaded, and the credential note is a necessary caveat. Every word earns its place; nothing extraneous.

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

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

The description covers the core functionality, the authentication requirement, and the conditional invoice inclusion. It does not describe the return format or error behavior, but with no output schema and a simple read operation, these are not critical. The tool is adequately described for an agent to invoke it 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 100%, so each parameter (order, secret, clientId, accessToken) is already documented in the schema. The description does not add any additional meaning or clarify parameter usage beyond what the schema provides. It adheres to the baseline without adding value.

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

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

The description states a specific verb ('Read') and resource ('the order'), and explicitly enumerates the scope: offer, payments, and invoice number. This clearly distinguishes it from sibling tools like create_order, start_payment, and accept_offer, which are all mutations. The purpose is unambiguous.

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

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

The description makes it obvious this tool is for reading order status, and its read-only nature contrasts with the mutation siblings. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use manifest for product details'). There is no exclusion guidance, so the usage context is implied rather than 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?

It discloses the critical one-time secret behavior: 'The secret is returned once and cannot be recovered.' It also explains how the returned credentials must be sent in the Authorization header, which is important context the annotations do not provide.

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

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

Four short sentences, each carrying distinct value: the result, the lack of prerequisites, the one-time secret warning, and how to use the credentials. It is entirely front-loaded with no filler.

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

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

Even without an output schema, it states the return contract — 'a client identifier and a secret' — and exactly how to consume those values in later calls. For a two-parameter registration tool, nothing essential 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 coverage is 100%, and both required parameters have clear descriptions in the schema. The description itself adds no parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb, 'Register yourself,' and names the exact deliverable: 'a client identifier and a secret.' This clearly distinguishes it from the sibling commerce tools, establishing it as the auth-registration step rather than a domain operation.

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 establishes when to call this tool by saying the credentials are used 'for the other tools' and that 'no approval and no prior arrangement' are needed. There is no explicit exclusion, but it clearly implies this is the first step before using any sibling tool.

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

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

Annotations already declare destructive/non-idempotent/openWorld, and the description goes well beyond them: credential requirement, the two settlement paths, the KYA DNS precondition sequence, the on-chain rejection, and named error codes with HTTP statuses (OFFER_EXPIRED 409, FINAL_NOT_RELEASED 409, PAYMENTS_DISABLED 503). This is unusually rich 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?

Front-loaded with the action, then conditions, then prerequisites, then errors — a sensible ordering. It is dense and slightly long, but nearly every clause carries operational meaning (auth, KYA sequencing, error codes) rather than 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 carries the return burden: it explains what a hosted session is and that a delegated token settles directly, and enumerates failure modes. It stops short of describing the concrete response payload (session handle/URL, settlement identifiers) an agent would need to continue the flow.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the hosted-session consequence of omitting sharedPaymentToken and the delegation model behind it. It does not add timing or formatting detail for order/accessToken, hence not a 5.

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+resource (start payment for a stage) and immediately splits the behavior into two mutually exclusive modes: hosted session vs delegated token settlement. It also names the KYA prerequisite tools (kya_challenge, kya_verify, kya_status), so an agent can place it relative to 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 says when each mode applies: omitted sharedPaymentToken yields a hosted session, a delegated token settles directly. It also states the precondition chain for self-registered agents (DNS domain-control KYA before payment) and the negative constraint that KYA does not grant buyer payment authority.

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