Brand Design Ltd.

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

The description adds meaningful behavioral context beyond the annotations: it explains that the action locks the billing identity, offer version, and terms hash at a point in time and prevents later changes from being accepted. This is useful for understanding irreversible side effects that annotations alone do not 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?

Two tight sentences that state the action first and then explain important locking semantics without any filler. Every sentence adds value, and the structure front-loads the core purpose.

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

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

For a tool with 7 parameters, 5 required, a nested billing object, and no output schema, the description is too thin. It does not explain what happens on success, what the response contains, how order relates to the offer, or the role of accessToken/clientId, leaving significant gaps 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?

The description implicitly maps billing to 'billing identity', offerVersion to 'offer version', and termsHash to 'hash of the terms', adding meaning to a few parameters. However, with schema description coverage at only 43%, it does not compensate for undocumented parameters like order or accessToken, and leaves their roles unclear.

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

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

The description clearly states the action ('Accept the offer on behalf of the buyer') and adds specific detail about locking the billing identity, offer version, and terms hash. It does not explicitly differentiate from siblings like create_order or start_payment, but the core 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?

There is no guidance on when to use this tool versus alternatives such as create_order or start_payment, nor any prerequisites or exclusions. The usage context is only implied by the tool's name and 'on behalf of the buyer', which is not sufficient for correct 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=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?

It clearly describes the return payload (order, offer, access token), warns that the token must be kept, and explains the edge case for services without a catalogue price. Annotations already indicate a non-read-only, non-idempotent, non-destructive operation, and the description adds meaningful behavioral context 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?

Two sentences deliver the essential action, return values, a required follow-up behavior, and an edge case. There is no filler, and the most important 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?

Despite having no output schema, the description covers the key return elements and an important special case. It does not describe error behavior or the exact lifecycle after creation, but the core call sequence is sufficiently clear for an agent to proceed.

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

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

Schema description coverage is 100%, so the parameters are already fully documented structurally. The description adds context around catalogue pricing and service-page hashes, but it does not materially enrich the meaning of individual parameters beyond what the schema provides.

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 and resource ('Place an order for a service') and clearly identifies the core action. It does not explicitly name sibling tools, but the action is distinct from accepting an offer, checking status, or starting 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 implies when to use the tool—when placing an order—and gives useful context about follow-up calls and unpriced services. However, it never explicitly contrasts this tool with alternatives like accept_offer or start_payment, so usage guidance remains mostly implicit.

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, so the description only needs to add context beyond that. It adds the detail that the invoice number is included once issued, which is useful. However, it doesn't disclose auth requirements or error handling, but for a simple read operation this is acceptable.

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

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

The description is a single, concise sentence that front-loads the action ('Read') and specifies the resource and an additional detail (invoice number). There is zero waste, and all information is essential.

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 tool with a readOnlyHint annotation, the description covers the main purpose and mentions the invoice number. However, it omits response format, error behavior, and authentication specifics, which could be relevant for correct invocation but are not critical for basic usage.

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 only 50% (order and accessToken lack descriptions), and the tool description provides no parameter explanations at all. It fails to compensate for the missing schema descriptions, leaving agents to infer the meaning of 'order' and why accessToken is 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?

The description clearly states the tool reads the current state of an order and its payments, including the invoice number once issued. This specific verb+resource structure distinguishes it from write-oriented siblings like create_order and start_payment, making selection straightforward.

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 that this tool is for reading order status, which implicitly separates it from creation or payment tools. While it doesn't explicitly name alternatives or exclusion conditions, the purpose is unambiguous given the sibling names, so it's adequate.

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 mark this as a mutating, non-idempotent operation, and the description adds meaningful behavioral detail beyond that: hosted session vs direct settlement, the ability to hand the session to another person, and the explicit rejection of on-chain payment. It does not detail error cases or side effects on the order, but the core behavioral traits are transparent.

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

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

The description is front-loaded with the core purpose and then efficiently explains the two payment modes. Each sentence contributes relevant information; the final sentence about on-chain payment is a useful restriction. It is compact without being sparse, though slightly verbose in the middle sentence.

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 should convey what the caller receives, and it does say a hosted payment session is returned. However, it does not describe the response shape, completion flow, error behaviors, or what 'order' refers to precisely. The description is adequate for basic invocation but leaves gaps for an agent needing to handle responses.

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 67%, and the description adds important meaning beyond the schema by explaining the behavior associated with tokens: 'Without a token' yields a hosted session, while a 'delegated shared payment token' causes direct settlement. This clarifies the role of accessToken and sharedPaymentToken, though 'order' remains underspecified.

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: 'Start payment for a stage.' It clearly identifies the action and names the result (hosted payment session or direct settlement). It does not explicitly contrast itself with siblings like accept_offer or create_order, but the purpose is concrete and 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 provides clear usage context by explaining two modes: without a token you get a hosted session, and with a delegated shared payment token the payment settles directly. It does not explicitly name alternatives or when-not-to-use conditions, but the behavioral guidance is sufficient for selecting this tool in most cases.

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