nexez_directoryBrowse the cross-merchant Nexez directory (optionally filtered by category, query, minimum readiness, or location).
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| category | No | ||
| location | No | ||
| min_readiness | No |
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.
Add one secure layer between your agents and this server.
Each tool targets a distinct action—browsing, fetching a manifest, searching, validating checkout, and validating negotiation. Directory and search both surface listings but are differentiated enough by browse vs. ranked search intent.
All tools share the nexez_ prefix and use snake_case, with most following a verb_noun pattern. nexez_directory is the one deviation since it uses a noun instead of a verb, but the overall pattern remains recognizable.
Five tools is well-scoped for a focused commerce discovery and validation server. Each tool serves a distinct purpose without unnecessary redundancy.
The toolset covers discovery, detail retrieval, and pre-transaction validation for checkout and negotiation. Actual payment execution and negotiation submission are not included, but the descriptions explicitly frame this as a validation-only surface, so the core workflow is well covered.