Nexez Agentic Commerce

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds that this is the cross-merchant directory and that filtering is optional, but it does not disclose return format, pagination, or result-size expectations. With annotations covering the safety profile, this is adequate but not rich.

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?

One sentence with no filler. The core action and resource are front-loaded, and the optional filtering behavior is appended in a compact parenthetical. Every phrase 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 read-only browse tool with no required parameters and no output schema, the description gives enough to attempt an invocation. However, it lacks guidance on output shape, pagination, and how this directory browse relates to nexez_search and nexez_get_page, leaving some ambiguity for an agent deciding between tools.

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 0% description coverage, so the description must compensate. It does so by explicitly naming the four filter dimensions: category, query, minimum readiness, and location. This maps cleanly to q, category, min_readiness, and location, adding meaning the bare schema does not provide, though it leaves some specifics (e.g., readiness scale, location format) implicit.

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 names a specific verb ('Browse') and a specific resource ('cross-merchant Nexez directory'), and lists the available filters. It is clear about what the tool does, but it does not explicitly distinguish itself from sibling tools like nexez_search, so it stops short of a 5.

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?

No guidance is given for when to use this tool versus nexez_search or nexez_get_page. The description implies browsing with optional filters, but it never states the preferred scenario, exclusions, or 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 indicate this is read-only and non-destructive, and the description does not contradict them. It adds useful behavioral context by specifying what the fetched manifest contains: seller profile, offers, and actions.

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?

One sentence with no filler. The verb and target resource are front-loaded, and the parenthetical clarifies the return contents without bloating the description.

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 one required parameter, the description is nearly complete: it states the input and the expected return contents. It could be slightly stronger by noting behavior for unknown slugs or pointing to discovery tools, but these are minor gaps.

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

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

Schema coverage is 100% and the slug parameter is already described as 'Listing slug'. The description adds 'by slug' but no additional format, uniqueness, or sourcing details 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 ('Fetch'), names the resource ('a listing's full structured agent manifest'), and scopes it by slug. This clearly distinguishes it from sibling discovery tools like nexez_directory and nexez_search.

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

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

The phrase 'by slug' implies this tool should be used when the agent already has a slug and needs the full listing manifest. However, it does not explicitly state when to prefer this over sibling tools, such as using nexez_search when the slug is unknown.

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 this as read-only, open-world, and non-destructive. The description adds meaningful behavioral context by noting ranked results and the inclusion of offers and agent.json URLs. It doesn't explain ranking criteria or open-world limitations, but the annotations carry the safety profile.

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

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

The description is two terse, front-loaded sentences with no filler. It states the scope and the return shape efficiently, which is appropriate for a search tool.

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 tool, the description gives the essential purpose and result shape. However, with 14 parameters, only 36% schema coverage, and no output schema, more guidance on filter semantics, ranking behavior, and response structure would be needed for fully reliable invocation.

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 only 36%, and the description does not compensate for the low coverage. It only reinforces the meaning of 'q' as a buyer request; it does not clarify lat/lng, category, industry, verified, min_trust, price_band, readiness, or checkout/negotiation filters. This leaves many parameters under-specified.

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 action ('Search across all Nexez merchants') and clearly identifies the resource (merchant services/products) and return contents (ranked listings with offers + agent.json URLs). This differentiates it well from the sibling directory, page, and validation 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: this is the cross-merchant search tool for matching buyer requests. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to infer its primary role among the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the concrete guarantee 'Never charges' and specifies the validation scope (offer, currency, payment readiness), which enriches the annotation with operation-specific behavioral detail.

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?

A single, front-loaded sentence delivers purpose, timing, validations, and side-effect safety with zero filler. Every clause 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?

Given 6 parameters, a nested object, no output schema, and no clarity on what 'slug' identifies or how to structure offerConfiguration, the description is too thin for an agent to reliably construct a correct call. The safety guarantees are clear, but the invocation details are not.

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% (3 of 6 params described), and the description adds no parameter-specific meaning. The required 'slug' is entirely undocumented in both schema and description, and there is no guidance on buyerEmail, buyerReference, or how to fill the nested offerConfiguration object.

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 ('Dry-run'/'validates') and resource ('a checkout for an offer'), with clear scope: 'BEFORE paying' and 'Never charges.' It also lists what is validated ('offer, currency, and payment readiness'), distinguishing it from sibling tools like directory/search/negotiation.

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 communicates when to use it — before payment, as a dry-run — and explicitly states a key non-condition: it never charges. It does not name alternative tools or give when-not-to-use exclusions, 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 already mark it read-only and non-destructive; the description adds the useful behavioral facts that it is a dry-run, returns a rules evaluation, and never writes. This goes beyond the structured fields by clarifying the no-side-effect nature and the result shape.

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, all informative: purpose, output, and side-effect profile. The critical 'BEFORE submitting' guidance is front-loaded and no filler is present.

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 7-parameter tool with no output schema and only 29% parameter documentation, the description is too thin: it does not define required inputs like slug or offer format, nor the shape of the returned rules evaluation. The safety profile is covered by annotations, but call preparation is not.

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 very low (29%) and the description does not compensate: only 'negotiation proposal' loosely maps to the offer parameter, while slug, query, budget, timeline, and requestedTerms remain unexplained. It adds only minimal context 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?

Uses the specific verb 'dry-run' plus a precise resource ('a negotiation proposal') and a specific rule context ('seller's rules'), clearly distinguishing this from the checkout-validation sibling. It states exactly what the tool evaluates, not merely repeating the title.

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 to use it BEFORE submitting a negotiation proposal, which is a clear invocation context. It does not name sibling alternatives or state when not to use it, though the negotiation scope already separates it from validate_checkout.

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