Nagora

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals the side effect of restoring listing stock and the hard limitation on canceling funded escrows. It could additionally mention what happens on invalid IDs or return behavior, but the core state-changing behavior is well disclosed.

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 convey the action, precondition, side effect, and exclusion. There is no filler or repetition, and the critical state condition 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?

The tool is simple with two parameters and no output schema. The description covers precondition, action, side effect, and fallback path, which is enough for correct invocation. A minor gap is the absence of any note about error/return behavior, but this does not materially hinder 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 description coverage is 100%, so the parameters are already fully documented in the schema. The description does not add new parameter-level meaning beyond reinforcing that orderId refers to an order in Initiated escrow state, which is sufficient for the baseline.

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 ('Cancels an order') and a precise resource with a qualifying state ('escrow is still Initiated'). It also clarifies the no-on-chain-funds condition, which differentiates this tool from other order-related siblings like confirm_delivery or get_order.

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 cancellation is valid (Initiated escrow), when it is not valid (Funded escrow), and directs the agent to the dispute/refund flow on the website instead. This gives clear when-to-use and when-not-to-use 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?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral consequence (releasing escrowed funds to the seller), the required precondition (escrowStatus Shipped), and the auto-finalise timer behavior if never called. It stops short of describing error handling or idempotency, but the critical financial effect is 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?

Three sentences, each earning its place: the action and effect, the precondition and urgency, and the fallback behavior. 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?

For a simple two-parameter tool with no annotations or output schema, this description is complete. It covers what the tool does, when to call it, what it requires, and what happens if it isn't called. Nothing essential is missing for correct 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 100%, so the schema already explains orderId and apiKey. The description adds no parameter-specific semantics, but none are needed at the schema baseline of 3.

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 (confirms arrival) and its concrete effect (releases escrowed funds), making the tool's role unambiguous. It is clearly differentiated from siblings like cancel_order and create_purchase by naming the exact transaction being confirmed.

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 a clear precondition ('Requires the order's escrowStatus to be Shipped') and explicit timing guidance ('Call promptly once delivery is verified'), plus the consequence of not calling. It doesn't name alternatives or when-not-to-use scenarios, but the context is sufficient to route an agent correctly.

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 no annotations, the description carries full burden. It discloses that the call does not fund the order, that escrow is per-order, that status changes automatically upon funds detection, and that shipping is conditional. It does not mention any destructive side effects or permissions, but for this tool the disclosed behavior is substantial and non-obvious.

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 action and the funding requirement. It is a single paragraph with a clear IMPORTANT note. It is somewhat lengthy but every sentence adds value; there is no fluff. It could be tightened, but it is well-structured and readable.

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 (7 parameters, 1 required) and no output schema, the description explains the return values and the funding workflow. It does not explicitly explain how to obtain variantId or deliveryOptionId, but the schema references get_listing, which is sufficient. The critical funding steps are covered, making it complete for correct 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 coverage is 100% for all 7 parameters, so the schema already documents each one. The description adds context about shippingAddress being required for physical listings, which the schema also states, and reiterates the funding flow, but it does not clarify variantId or deliveryOptionId beyond what the schema says. The description provides marginal value beyond the schema, so a baseline 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 starts with a specific verb and resource: 'Places an order against a listing.' It also names the return values (depositAddress and amountNano). It is immediately clear what this tool does and it is easily distinguished from siblings like cancel_order or get_order without needing to open the 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 description gives explicit step-by-step guidance: the order is not funded by this call, exactly amountNano must be sent to depositAddress, and physical listings require shippingAddress. It also explains the automatic transition to AwaitingShipment. This is actionable and removes ambiguity about the follow-up funding step.

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 annotations already declare readOnlyHint=true, and the description adds useful behavioral context beyond that: no API key needed, the response includes variants/delivery options/pricing, and the Nano total should be carried into purchase to guard against exchange-rate drift. This gives the agent actionable expectations about auth, return scope, and downstream use.

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 and none redundant. The core purpose is front-loaded, followed by auth context, return contents, and a specific downstream instruction—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 one-parameter read-only tool with no output schema, the description covers purpose, auth requirements, return content, and how to use the result in the purchase flow. Nothing critical is missing for an agent to call and use 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 input schema has 100% coverage for the single parameter listingId, including the note that it comes from search_listings. The description adds no additional meaning to this parameter, so the baseline of 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 opens with a specific verb+resource: 'Fetch a single listing by ID.' It is clearly differentiated from sibling search_listings (which searches rather than fetches by ID) and from order/receipt tools by naming the listing resource and the returned detail scope.

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 provides clear context for when to call this tool: to retrieve a single listing's full details, with no API key required. It also connects to the purchase flow by instructing the agent to use the returned Nano total as quotedTotalNano, though it does not explicitly state exclusions or name alternative tools for the same task.

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 annotation readOnlyHint=true already indicates a read-only operation, and the description does not contradict that. It adds behavioral context by stating it is a poll operation that returns data only when available ('once available' for receipt ID), implying the agent may need to retry. It does not mention error handling or rate limits, but these are minor gaps given the read-only nature.

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 fluff. The first sentence states the purpose and return fields, the second provides the timing guidance. It is front-loaded and 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 read-only poll operation with no output schema, the description covers the essential information: what it returns, when to call it, and how it relates to confirm_delivery. An agent has enough context to invoke it correctly without additional documentation.

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% because both parameters (apiKey and orderId) have descriptions in the input schema. The tool description does not add any additional parameter-level detail beyond what the schema provides, so the baseline score 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 clearly states the verb 'Polls' and the resource 'an order placed by this agent', and lists the specific fields returned (orderStatus, escrowStatus, funding timestamps, tracking info, receipt ID). It is distinct from siblings like cancel_order and confirm_delivery, which are actions, and get_receipt, which is a separate retrieval tool. The purpose is unambiguous and specific.

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 the tool: 'Poll after funding the deposit address, and after the seller ships, before calling confirm_delivery.' This gives clear timing and sequencing relative to other operations, and it also distinguishes from confirm_delivery by indicating it must be called before that action. This is explicit usage 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 annotations only provide readOnlyHint: true, so the description carries the burden of behavioral context. It adds that the receipt is cryptographically signed, includes a KMS signature, and that errors occur while the order is in progress—useful details beyond the read-only hint.

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. It front-loads the core purpose and then adds the availability constraint. Every word 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?

The description lists the receipt contents, the availability condition, and the error behavior. Although there is no output schema, the description gives sufficient detail for an agent to understand what it will receive and when to call it. Minor missing detail like the exact error format is not critical.

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 parameters (apiKey, orderId) are described adequately in the schema. The description does not add significant parameter-level detail beyond what the schema already provides, so a 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 clearly states the tool's function: returning a cryptographically signed receipt for a completed order, specifying key contents (seller Nano address, payout block hash, KMS signature). It also differentiates itself from sibling tools like get_order by focusing on the receipt and its unique availability condition.

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 the precondition: 'Available only after escrow is Released; returns an error while the order is still in progress.' This provides clear guidance on when to invoke the tool. It doesn't explicitly compare with alternatives, but the condition is 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?

The description discloses a critical behavioral trait beyond what annotations provide (none are given): the remote server has no local storage, so the API key is returned only once. It also explains the consequence (must store securely) and the alternative auth method (Authorization: Bearer header). This is exactly the kind of behavioral context an agent needs to avoid losing credentials.

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 paragraph of 4 sentences, front-loaded with the core purpose and the most critical warning (key returned once). It is efficient and every sentence earns its place, though it could be slightly more structured with line breaks for the key-return warning. Still, it is appropriately sized and readable.

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 no output schema and no annotations, the description covers all essential context: what it does, the critical one-time key return, how to use the key afterward, and when to skip it. It also names the sibling tool (whoami) for checking credentials. Nothing an agent needs to call it correctly 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 100%, so the schema already documents all 5 parameters. The description adds context for the 'nanoAddress' parameter ('the wallet this agent pays from') and clarifies the 'callbackUrl' purpose ('signed order state-change events'), but these are minor additions. Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'Creates a Nagora agent and mints its API key in one call.' It uses a specific verb ('Creates') and resource ('Nagora agent'), and explicitly distinguishes itself from the sibling tool 'whoami' by noting it should be skipped if a credential is already configured. This makes it easy for an agent to select it correctly.

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 when-to-use and when-not-to-use guidance: 'Skip this tool if a credential is already configured; check with whoami.' It also explains the critical usage pattern: the key is returned once, must be stored securely, and passed as apiKey on subsequent calls or via Authorization header for long-lived setups. This is comprehensive and actionable.

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 adds useful behavioral context by stating no API key is required and that the response contains an items array and total count. This goes beyond what the annotations alone convey 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 with no filler. It front-loads the main purpose, then adds the most important usage and response details in a compact, readable way.

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 search tool with seven parameters fully documented in the schema, the description covers the key contextual points: scope, authentication, response shape, and where to get more detail. A minor gap is the lack of any note about pagination or sorting behavior, but those are already in the schema.

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 schema fully documents all seven parameters including q, count, sortBy, and price filters. The description adds a high-level search intent but does not add parameter-level detail, which is acceptable given the complete schema coverage.

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 ('search') and resource ('active listings on nagora.shop'), making the tool's core function immediately clear. It also hints at its relationship to get_listing by saying full detail is available there, helping distinguish it from its sibling.

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 use: it is for searching active listings, requires no API key, and explicitly directs the agent to use get_listing for full detail before purchasing. It names an appropriate alternative but does not fully enumerate when not to use the tool beyond that distinction.

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 annotation readOnlyHint=true already establishes the read-only nature. The description adds value by detailing exactly what is returned (identity, spending caps, callback URL, webhook secret) and that it verifies the credential, giving useful context beyond the annotation.

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 concise sentences: the first states the core purpose, the second provides usage guidance. Every sentence earns its place, with no filler or redundancy.

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 optional parameter, the description covers the return values explicitly and gives a clear usage directive. The annotation covers the safety profile, so nothing critical 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?

The input schema covers 100% of the parameter with a clear description (apiKey and when to omit it). The tool description doesn't mention the parameter at all, so it adds no extra meaning. With full schema coverage, a 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 states a specific verb ('verifies', 'returns') and a clear resource (the agent's identity, spending caps, callback URL, webhook secret). It distinguishes itself from sibling tools, which all relate to orders, listings, or registration, so an agent can easily tell it apart.

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 instructs 'Call this first to confirm the credential works,' providing clear timing and purpose. It doesn't explicitly name alternatives, but the sibling tools are functionally distinct, so there's little ambiguity about when to use this one.

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