Server Quality Checklist

Tool Scores

• import_qi_walletA
  3.7/5.0
  Behavior4/5

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

  The annotations only record that this is not read-only/destructive, leaving behavioral context to the description. The description adds that the mnemonic is encrypted at rest, that the phrase is not emitted in the tool's output, and that the receiving address is deterministically re-derived from the phrase, which materially informs the agent about privacy and determinism. It does not contradict 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.

  Conciseness4/5

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

  Three sentences, all useful, with the core action front-loaded and the encryption/output caveat earning its place. The phrasing around 'only the mnemonic is encrypted... never the phrase itself' is slightly redundant and awkward, keeping it from top marks for polish.

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

  Completeness4/5

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

  The tool description, schema, and annotations together let an agent select parameters correctly and understand the core operation, including encryption and deterministic derivation. Since there is no output schema, the absence of a precise return-value description or duplicate-import error behavior leaves a small but real gap.

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

  Parameters3/5

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

  Schema coverage is 100%, so the description need not repeat parameter details; the baseline is 3. It adds mild semantic color by tying the zone parameter to deterministic address re-derivation, but this largely mirrors the schema's own zone description rather than providing new meaning.

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

  Purpose4/5

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

  The description opens with a concrete action ('Import an existing Qi-ledger wallet...'), names the source (BIP-39 mnemonic) and destination (server's encrypted store), and goes beyond the title by mentioning deterministic address derivation. It clearly identifies this as an import operation for Qi wallets, though it does not explicitly contrast it with sibling tools like import_wallet or create_qi_wallet.

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

  Usage Guidelines3/5

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

  There is no explicit when-to-use statement or named alternative; the agent must infer that an existing Qi wallet with a mnemonic should use this tool rather than create_qi_wallet. The reference to 'Same encryption as create_qi_wallet' provides context but no exclusion or alternative-routing guidance, so usage guidance remains implied rather than stated.

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

• get_conversion_rateA
  3.8/5.0
  Behavior4/5

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

  Annotations already mark readOnlyHint, and the description reinforces 'read-only and doesn't move anything' while adding behavior beyond the annotation: the rate is current as of the latest block in the zone, it is on-chain, and the reverse direction is quote-only. This is valuable context even though the discussion of QI-to-QUAI support is questionable given the sibling list.

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

  Conciseness4/5

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

  The description is front-loaded with the core purpose and each sentence adds substantive context: what is quoted, how to actually convert, and the reverse-direction limitation. It is slightly long, but the extra clauses about the built-in swap and wallet differences earn their place.

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

  Completeness3/5

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

  The definition covers the tool's domain, zone/network behavior, read-only nature, and conversion limitations. However, it does not describe the response shape or numeric rate format, and with no output schema that gap matters; it also overlooks the convert_qi_to_quai sibling when discussing QI-to-QUAI support.

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

  Parameters4/5

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

  The schema already documents all four parameters with descriptions and enums, so the baseline is 3. The description adds useful meaning by clarifying that amounts are in the source currency's human units and that quai_to_qi is executable via send_transaction while qi_to_quai is quote-only, going beyond the enum values.

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

  Purpose5/5

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

  The first sentence clearly names the operation ('Quote a conversion') and identifies the two native ledgers (QUAI and Qi), and the rest scopes it to an on-chain rate at the latest block in a zone. It also distinguishes this from a third-party DEX and from send_transaction, so an agent can tell what this tool is for.

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

  Usage Guidelines2/5

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

  The description gives useful routing: use send_transaction to actually convert QUAI to Qi, and treat qi_to_quai as quote-only. However, it claims QI-to-QUAI conversion is not supported by this server, even though a sibling tool named convert_qi_to_quai exists; it should mention that sibling as the alternative instead of declaring the operation impossible. That makes the guidance partially misleading.

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

• import_walletA
  4/5.0
  Behavior4/5

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

  The annotations only indicate readOnlyHint=false, idempotentHint=false, etc., so the description carries the burden of explaining behavior. It adds meaningful details: the private key is used once, never returned, and never logged; disk files use owner-only permissions; the password is not stored; and the address's zone is auto-detected and cannot be changed. It does not describe failure behavior on duplicate names, but the schema already covers the uniqueness constraint.

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

  Conciseness5/5

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

  The description is compact: three sentences, with the core purpose front-loaded, then security-relevant details, then zone behavior. Every sentence adds distinct information without redundancy or filler.

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

  Completeness4/5

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

  For a mutating tool with no output schema, the description covers the invocation-critical aspects: purpose, parameter handling, security, and zone constraints. It does not state what the successful return value is, which would be helpful, but an agent can reasonably infer completion and use related tools like list_wallets to verify. This leaves only a minor completeness gap.

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

  Parameters3/5

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

  Schema description coverage is 100%, with all three parameters already documented (name constraints, password minimum, private key format). The description adds security context, such as 'never returned or logged,' but does not meaningfully expand parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb (import), a specific resource (an existing Quai private key), and the storage outcome (encrypted wallet store under a name/password). It also connects the tool to send_transaction, making its purpose concrete. It distinguishes itself from create_wallet by focusing on an existing key, and from import_qi_wallet by explicitly saying 'Quai private key'.

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

  Usage Guidelines3/5

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

  The description gives clear context: use this when you have an existing Quai private key and want to avoid passing it around for future send_transaction calls. However, it does not explicitly say when to prefer create_wallet, import_qi_wallet, or another sibling, nor does it state exclusions. The usage guidance 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.

• get_blockA
  4.4/5.0
  Behavior4/5

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

  Annotations already establish read-only behavior, and the description adds non-obvious context: block numbers are not globally unique across Prime/Region/Zone, so the shard is mandatory. It also clarifies accepted identifier formats and the address-to-zone precondition. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is three sentences with no filler. The core capability and the non-obvious shard prerequisite are front-loaded, and the trailing resolve_zone pointer is directly relevant to correct invocation.

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

  Completeness4/5

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

  Given the complex chain hierarchy and the absence of an output schema, the description covers the essential operational knowledge: how to specify the chain, what identifiers are accepted, and the address-to-zone precondition. It does not describe the response shape, but that is not required to select or invoke the tool correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete chain examples (cyprus1, cyprus, prime), explaining the accepted block identifier forms, and stressing that shard disambiguates the block lookup beyond what the enum alone conveys.

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

  Purpose5/5

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

  Description begins with 'Fetch a block from a specific Quai Network chain' — a precise verb and resource. It then unpacks the hierarchy requirement so an agent won't confuse block lookup with transaction lookup, and the shard-qualification warning distinguishes its invocation semantics from ordinary single-chain block fetchers.

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

  Usage Guidelines4/5

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

  It explains when the tool is the right call: fetching a block by number, hash, or tag on a particular shard. It also gives a concrete routing rule — if you only have an address, call resolve_zone first. It doesn't explicitly say when not to use it versus get_transaction, but the read-context is clear.

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

• create_walletA
  4.5/5.0
  Behavior5/5

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

  The description goes far beyond the minimal annotations (which only state readOnlyHint=false, etc.) by disclosing encryption details (V3 keystore, scrypt, AES-128-CTR, MAC), file permissions, that the private key is never returned or logged, that address generation 'grinds' until it lands in the requested zone, and that a paired Qi wallet is created by default. This is rich, actionable behavioral context.

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

  Conciseness4/5

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

  The description is long but information-dense, with no fluff. It opens with the core purpose and then systematically covers security, behavior, and usage. Some details, like the exact keystore cipher suite, could be seen as more than strictly necessary, but they serve to build trust and clarify behavior, so every sentence earns its place.

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

  Completeness4/5

  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, the description thoroughly covers what happens, what is stored, how security works, and how to spend later. The only notable gap is that it never states what the tool actually returns (e.g., wallet address or confirmation). This is a minor omission given the depth of other context, but it is still a gap for an agent that needs to use the result.

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

  Parameters4/5

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

  Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaningful context beyond the schema: it explains why 'zone' matters (location-aware addresses, grinding), that 'password' is reused for the paired Qi wallet, and what pairQiWallet=true actually implies for conversions. This elevates it above the baseline.

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

  Purpose5/5

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

  The description uses a specific verb ('Generate') and names the precise resource ('Quai (QUAI-ledger) private key and address'), clearly distinguishing it from import_wallet by emphasizing 'brand-new' and from create_qi_wallet by explaining the paired Qi wallet behavior. The custodial-store framing and explicit tie to send_transaction leave no ambiguity about what this tool is for.

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

  Usage Guidelines4/5

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

  The description explicitly says to use send_transaction with the wallet's name and password to spend from it, and gives a concrete condition for skipping the paired Qi wallet via pairQiWallet=false. It does not explicitly contrast with import_wallet or create_qi_wallet, but the 'brand-new' wording and paired-wallet explanation imply the appropriate alternatives, so the guidance is clear if not exhaustive.

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

• get_transactionA
  4.5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description specifies exactly what the tool returns, including the conditional nature of the receipt ('when available'), and explains the automatic zone-resolution behavior. This is especially valuable because there is no output schema to carry that information.

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

  Conciseness5/5

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

  Two focused sentences cover the operation, the return fields, and the important zone/shard caveat without repetition or filler. The core lookup behavior is front-loaded, and every clause adds useful information.

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

  Completeness5/5

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

  Given the simple two-parameter schema, fully documented parameters, and read-only annotations, the description is complete enough for an agent to select and invoke the tool correctly. It supplies the return contract that would otherwise be missing due to the lack of an output schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both hash and network parameters are already well documented in the schema. The description reinforces that lookup is by hash but adds no meaningful parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific action ('Look up a transaction on Quai Network by its hash') and names the returned details (from, to, value, gas, status) plus receipt. The automatic zone/shard resolution distinguishes it clearly from related tools like resolve_zone and from balance/block lookups.

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

  Usage Guidelines4/5

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

  The description clearly establishes when to use the tool: when you need transaction details by hash. It also explicitly tells the agent it does not need to know the zone/shard in advance, preventing unnecessary calls to resolve_zone. However, it does not name alternative tools or state exclusion conditions.

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

• list_walletsA
  4.5/5.0
  Behavior4/5

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

  Annotations already mark the operation read-only; the description adds meaningful behavioral context by disclosing that no password is required and that addresses are stored in the clear alongside encrypted keys, with only spending requiring the password. It also specifies the output fields since no output schema exists.

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

  Conciseness5/5

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

  Three sentences all carry signal: the scope, the security-relevant behavior, and the downstream use. It is front-loaded with the core action and avoids filler or repetition of the schema.

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

  Completeness5/5

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

  For a zero-parameter, read-only listing with no output schema, the description is fully self-sufficient: it names the resource, included wallet types, every returned field, the auth requirement, and downstream tools that consume the output.

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

  Parameters4/5

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

  The tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to add. The no-parameter baseline of 4 applies; the description correctly spends no space on parameters.

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

  Purpose5/5

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

  The description states a specific action ('List every wallet stored in this server's encrypted wallet store'), identifies both ledger types, and enumerates the returned fields (name, ledger, address, zone). It clearly distinguishes this tool from create/import/send siblings by framing it as the enumeration endpoint.

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

  Usage Guidelines4/5

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

  It explicitly states the primary use ('Use this to find the walletName to pass to send_transaction, get_qi_balance, or convert_qi_to_quai') and clarifies that no password is needed. It does not explicitly contrast with alternative lookup tools, but for a listing tool the context is clear enough.

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

• search_docsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this by noting it is 'an offline index, not a live web search.' It also discloses the limitation that results only cover topics in the curated index and instructs the agent to avoid guessing. This adds useful behavioral context beyond the minimal annotations.

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

  Conciseness5/5

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

  Three dense sentences contain the action, the scope, concrete usage examples, and an explicit limitation/fallback path. Every sentence earns its place, and the key purpose is front-loaded.

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

  Completeness5/5

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

  For a simple two-parameter read-only search tool, the description covers what it searches, what it returns (snippets with links), when to use it, and how to handle misses. No output schema is present, but the return format is sufficiently described. The agent can invoke this tool correctly without further information.

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

  Parameters3/5

  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. The description adds helpful query examples for the query parameter, which improves usability, but it does not enrich the semantics of maxResults beyond what the schema provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb ('Search') and resource ('small curated index of Quai Network developer documentation') and states the output ('relevant snippets with links to the official docs'). It clearly distinguishes this documentation-search tool from the on-chain/sibling tools like get_transaction or get_balance.

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

  Usage Guidelines5/5

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

  It explicitly says when to use the tool ('explain a Quai concept, find the right doc page, or clarify terminology') and gives a concrete fallback behavior for uncoveed topics: say so and point at docs.qu.ai rather than guessing. This is strong, actionable usage guidance.

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

• create_qi_walletA
  4.6/5.0
  Behavior5/5

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

  All annotations are false, so the description carries the full disclosure burden. It discloses that the wallet is HD/mnemonic-based, that only the mnemonic is encrypted at rest using a specific V3 keystore scheme, and that the mnemonic is never returned. It also warns that without a Qi wallet converted funds may be unrecoverable, a meaningful behavioral consequence beyond what annotations or schema provide.

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

  Conciseness5/5

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

  The description is substantial yet dense: purpose, usage, internal behavior, security, and alternative routing are each covered in order with no redundant filler. The most decision-relevant information—what it creates, when to use it, and what happens without it—is front-loaded.

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

  Completeness4/5

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

  The description covers prerequisites, consequences, alternatives, internal mechanics, and security, which is unusually complete for a create tool with no annotations and no output schema. The only gap is that it never states what the successful response contains (e.g., address, zone, or name), which an agent may need when using the returned wallet; this keeps it from a perfect score.

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

  Parameters3/5

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

  Schema description coverage is 100%, and each parameter already has clear semantics. The description reinforces that name and password are used for storage/encryption and hints at zone/name as reasons for direct use, but it adds little beyond what the schema already documents. The baseline of 3 for full schema coverage is appropriate.

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

  Purpose5/5

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

  The description names a specific verb and resource ('Generate a new Qi-ledger wallet'), identifies the ledger type (UTXO-based), and explicitly contrasts it with account-based QUAI wallets from create_wallet. This makes the tool's purpose unambiguous and clearly differentiates it from the closest sibling.

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

  Usage Guidelines5/5

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

  It states exactly when to use this tool: as a destination for QUAI->Qi conversions (citing send_transaction / get_conversion_rate) and later convert_qi_to_quai. It also names the alternative create_wallet with pairQiWallet and the conditions for direct use (standalone Qi wallet or different zone/name), giving the agent both inclusion and exclusion rules.

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

• get_qi_payment_codeA
  4.6/5.0
  Behavior5/5

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

  The description goes well beyond the readOnlyHint annotation: it explains that the operation is purely local with no network call, that it requires the password because BIP-47 key material is derived from the mnemonic, and that a fresh on-chain address is derived behind the scenes per sender. This gives the agent a clear behavioral model.

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

  Conciseness5/5

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

  The description is a single, information-dense passage with no filler. It front-loads the core action and definition, then efficiently explains the key distinction, the password requirement, and the local nature of the operation. Every sentence contributes essential information.

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

  Completeness4/5

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

  For a simple read-only getter with a fully documented schema and relevant annotations, the description covers the important behavioral context: purpose, usage, password need, and local execution. It does not explicitly describe the return value format, but given the tool name and context, an agent can reasonably infer it returns the payment code.

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

  Parameters4/5

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

  Schema description coverage is 100%, satisfying the baseline. The description adds meaningful context by explaining why password is required and that the derivation is local, which helps the agent understand the role of that parameter beyond the schema's 'The wallet's password.' It does not repeat every parameter, but it adds value where it matters.

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

  Purpose5/5

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

  The description names a specific verb and resource: 'Get the reusable BIP-47 payment code for a Qi wallet.' It further clarifies what the thing is for and explicitly distinguishes it from an on-chain address, so an agent can clearly understand the tool's unique purpose relative to siblings like send_qi and get_qi_balance.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: this is what you hand someone so they can send you Qi via send_qi, analogous to handing out an address. It does not explicitly enumerate when not to use it or name alternative tools beyond referencing send_qi, but the intended use case is well conveyed.

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

• resolve_zoneA
  4.6/5.0
  Behavior4/5

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

  The annotations already establish read-only behavior (readOnlyHint=true), and the description adds meaningful context beyond that: it performs no network call, works purely via local inspection, and treats addresses as zone-bound. This informs the agent about determinism and side-effect-freedom without contradicting 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.

  Conciseness5/5

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

  The description is compact and front-loaded: the core purpose and key differentiator ('no network call') appear in the first sentence, followed by a concise background explanation and a clear usage note. No redundant or filler content is present.

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

  Completeness4/5

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

  For a single-parameter, read-only, local parsing tool, the description covers what the tool does, why it matters, and when to use it. It does not detail the exact return shape or invalid-address handling, but the absence of an output schema makes this a minor gap rather than a blocking one.

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

  Parameters4/5

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

  The schema already documents the single 'address' parameter with 100% coverage. The description adds value by explaining that the address encodes both zone and ledger and by giving concrete zone examples ('cyprus1, paxos2, hydra3'), which helps the agent interpret the input and understand what the output represents.

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

  Purpose5/5

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

  The description states a specific action ('Determine which Quai Network shard/zone a given address belongs to'), names the resource (address), and explicitly distinguishes its mode ('purely by inspecting the address (no network call)'). It also clarifies the conceptual model (location-based addressing, zone and ledger encoded in bytes), which removes ambiguity about what the tool resolves.

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

  Usage Guidelines5/5

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

  The description gives explicit guidance on when to use this tool: 'Use this before get_balance, get_transaction, or call_contract if you need to explain or confirm which part of the network an address or transaction belongs to.' It also implies a non-network, local operation, helping the agent choose it over network-dependent siblings.

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

• get_balanceA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral detail: it automatically resolves the correct zone, returns balances in both raw wei and formatted QUAI, and requires no gas, signing, or private key. These details are especially useful because there is no output schema.

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

  Conciseness5/5

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

  The description is compact and front-loaded: the core purpose appears in the first sentence, followed by the most important behavioral caveat and return format. Every sentence contributes context without redundancy or filler.

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

  Completeness5/5

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

  For a read-only query tool with three well-schema-documented parameters, the description covers all essential aspects: what is returned, the automatic zone resolution behavior, and the absence of signing/gas requirements. The lacking output schema is partially mitigated by explicitly stating the return units.

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

  Parameters4/5

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

  Schema coverage is 100%, so parameters are already well documented. The description adds value by clarifying that the address parameter is sufficient and that zone/shard selection is resolved internally, which prevents an agent from searching for a nonexistent zone parameter. It does not add meaning for network or blockTag, but the schema already covers those.

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

  Purpose5/5

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

  The description clearly identifies the action (get), the resource (QUAI balance of an address), and the network (Quai Network). It also distinguishes itself from siblings such as get_qi_balance by explicitly naming QUAI, and from resolve_zone by stating that zone resolution is handled automatically.

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

  Usage Guidelines4/5

  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 the tool: whenever an agent needs an address's QUAI balance, and it explains that no shard specification is needed. It does not explicitly mention when not to use it or name alternatives like get_qi_balance, so it stops short of full when/when-not guidance.

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

• send_transactionA
  4.7/5.0
  Behavior5/5

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

  The description adds substantial behavior beyond the annotations: the mandatory two-step confirmation, password only held in memory and never stored or logged, automatic ETX handling with slower finality, and the QUAI-to-Qi conversion path. This is exactly the kind of non-obvious behavior an agent needs, and it does not contradict the destructiveHint/readOnlyHint annotations.

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

  Conciseness5/5

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

  The description is longer than average, but every sentence earns its place: purpose, sharding/ETX behavior, conversion context, two-call workflow, and security guarantee. It is front-loaded with the core action and then layers necessary procedural detail.

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

  Completeness5/5

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

  For a destructive, non-idempotent mutation tool with no output schema, the description is unusually complete. It tells the agent exactly what the preview returns, when the password is required, what confirmationToken is, and what happens in the ETX and conversion cases. There is very little left for the agent to infer.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description enhances this by explaining the lifecycle of confirm, password, and confirmationToken across the two required calls, and it contextualizes amount as QUAI not wei, matching but reinforcing the schema.

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

  Purpose5/5

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

  The description clearly states the verb and resource: 'Send QUAI from a wallet in this server's encrypted store to a recipient address.' It goes further by distinguishing same-zone sends, ETX sends, and QUAI-to-Qi conversions, making it easy to separate from sibling tools like get_conversion_rate and send_qi.

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

  Usage Guidelines4/5

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

  It gives explicit workflow guidance: always requires two calls, first without confirm for a preview, then with confirm, confirmationToken, and password to broadcast. It points to get_conversion_rate as a quote-without-sending alternative. However, it does not explicitly say 'for pure Qi sends use send_qi,' so the exclusion of a close sibling is left implicit.

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

• call_contractA
  4.9/5.0
  Behavior5/5

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

  Annotations already indicate readOnlyHint and openWorldHint, but the description adds significant behavior beyond them: it never spends gas, never requires a key, simulates without broadcasting state-changing calls, and returns decoded results. This is rich, non-redundant context that helps the agent predict side effects.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, then the required inputs, then behavioral caveats and the alternative. Every sentence adds value; there is no filler or repetition of schema content beyond what is necessary for clarity.

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

  Completeness5/5

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

  For a read-only call tool with 5 parameters and no output schema, the description covers purpose, input requirements, behavior, limitations, and the alternative tool. It even notes that state-changing calls are simulated rather than broadcast, which fully prepares the agent for expected outcomes.

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

  Parameters4/5

  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 meaningful guidance: it tells the user to provide the address, an ABI fragment array containing at least the method, the method name, and arguments. It also clarifies that zone resolution is automatic, which indirectly explains the network parameter's role.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Perform a read-only call (an eth_call equivalent) against a deployed EVM contract on Quai Network and return the decoded result.' It distinguishes itself from siblings by explicitly contrasting with the not-yet-available send_transaction tool and clarifying it cannot change state.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: it works for view/pure methods and simulates state-changing ones, but cannot change on-chain state. It names the alternative tool (send_transaction) for state changes, and notes the zone is resolved automatically so users don't need a zone-resolution step.

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

• convert_qi_to_quaiA
  4.9/5.0
  Behavior5/5

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

  Annotations already mark this as mutating and destructive, but the description adds substantial behavioral detail: the preview call needs no password, the preview cannot verify Qi balance because of wallet reconstruction, and a confirm may fail with insufficient funds after a clean preview with the failure reported plainly and no silent retry. This goes well beyond the annotations and matches them.

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

  Conciseness5/5

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

  Four dense sentences, each earning its place: core action, sibling relationship, two-step flow, and a critical failure caveat. The description is front-loaded with the purpose and then layers usage and risk information efficiently.

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

  Completeness5/5

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

  Despite no output schema, the description provides prerequisites (wallet must come from create_qi_wallet/import_qi_wallet), the two-step invocation pattern, the need for confirmationToken and password, and the possible late insufficient-funds failure. An agent has effectively all the contextual information needed to invoke this correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds a temporal dimension beyond isolated property descriptions, linking confirm, confirmationToken, and password into the two-step flow and clarifying that the first call omits confirm. It reinforces that amount is in Qi, though the schema already states this.

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

  Purpose5/5

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

  States a specific verb ('Convert'), resource ('Qi held in a wallet created with create_qi_wallet/import_qi_wallet'), and target ('a QUAI-ledger address'). It also distinguishes itself from siblings by explicitly naming itself 'the other half of Quai's native ledger swap' and pointing to the reverse path in send_transaction.

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

  Usage Guidelines5/5

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

  Explicitly routes to alternatives: 'see get_conversion_rate and send_transaction's QUAI -> Qi path.' It gives precise when-to-use guidance by describing the two-step preview/confirm pattern and exactly when password and confirmationToken are required, leaving no ambiguity about the call sequence.

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

• get_qi_balanceA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses the actual mechanism: reconstructing the wallet from its mnemonic and querying network unspent outputs rather than reading a stored public address. It also explains spendable vs total balance, maturity exclusions, and the payment-code address derivation limitation.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose and then adds the differentiator, return semantics, and caveat in a logical order. Every sentence contributes meaningful guidance without filler or redundancy.

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

  Completeness5/5

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

  Given the readOnlyHint, openWorldHint, and fully documented schema, the description covers all non-obvious calling concerns: when to use it, why the password is needed, how the balance is computed, what the return values represent, and when counterpartyPaymentCodes is mandatory. The lack of an output schema is mitigated by the explicit return description.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds meaning to password by explaining why it is required (mnemonic reconstruction) and to counterpartyPaymentCodes by clarifying that payment-code addresses are pairwise-derived and otherwise undiscoverable. This goes beyond the schema's basic field descriptions.

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

  Purpose5/5

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

  The description states a precise action and resource: 'Check the Qi balance of a wallet', scoped to wallets created with create_qi_wallet or import_qi_wallet. It also distinguishes itself from get_balance (QUAI), so an agent can tell them apart without opening the schema.

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

  Usage Guidelines5/5

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

  It explicitly contrasts this tool with get_balance (QUAI) and explains why the password is needed for Qi UTXO balance reconstruction. It also gives the condition for when to pass counterpartyPaymentCodes for payment-code funds, naming send_qi as the relevant sibling.

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

• send_qiA
  4.9/5.0
  Behavior5/5

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

  Annotations only say readOnlyHint=false and destructiveHint=true, so the description carries the burden of explaining actual behavior. It does this thoroughly: two-step confirmation, preview requiring no password, confirm signing and sending, and the important caveat that preview cannot verify balance so confirm can fail despite a clean preview. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is detailed but every sentence earns its place. The core distinction (payment code vs plain address) is front-loaded, then the privacy rationale and two-step flow are explained compactly. It is appropriately sized for a tool with a non-obvious confirmation workflow.

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

  Completeness5/5

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

  Despite having no output schema and 8 parameters, the description covers what an agent needs: wallet prerequisites, recipient payment code origin, destination zone relevance, the exact two-step call sequence, and the insufficient-funds failure mode. Nothing critical is missing for correct invocation.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds meaningful workflow semantics beyond the schema: it explains how confirm, confirmationToken, and password relate to the two-step preview/confirm pattern, and it reinforces that amount is in Qi. This exceeds the baseline without duplicating the schema.

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

  Purpose5/5

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

  The description uses a specific verb and resource: 'Send Qi from a wallet ... to a recipient's BIP-47 payment code.' It explicitly distinguishes this tool from sending to a plain address, which separates it from siblings like send_transaction. It also ties the payment code to get_qi_payment_code, making the tool's purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description gives clear when-to-use guidance: use this for Qi peer-to-peer transfers to a payment code, not a plain address. It also names sibling tools with the same two-step pattern (send_transaction, convert_qi_to_quai) and explains the preview-then-confirm workflow, including when password and confirmationToken are required.

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