Server Quality Checklist

Tool Scores

• ravn_quoteA
  4.2/5.0
  Behavior4/5

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

  The description states it is free and requires no API key, adding useful behavioral context beyond the readOnlyHint annotation. It also explicitly says it returns a quoteToken and directs the user to ravn_execute, making the behavior and next steps transparent. No contradictions with annotations exist.

  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 concise, one sentence with a clear structure. It front-loads the primary action (get a swap quote), then provides key attributes (cross-chain, 16 chains, native Bitcoin/Solana, free), and ends with the output and follow-up step. Every word adds value without redundancy.

  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 tool's complexity (11 parameters, no output schema), the description adequately explains the tool's role, what it returns (a quoteToken), and how to use that output with ravn_execute. It does not describe the quote structure or error cases, but that information is not necessary for basic invocation since parameters are fully documented. The description covers the essential context.

  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 baseline is 3. The main description does not add additional parameter-level clarifications beyond what the schema already provides. It reinforces the overall purpose but does not enhance understanding of individual parameters, so a score of 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 clearly states the tool's function: obtaining a swap quote from RAVN, including same-chain and cross-chain across 16 chains. It specifies the resource (RAVN), the action (get a quote), and the scope, and it distinguishes itself from ravn_execute by explaining that the returned quoteToken is passed to ravn_execute for execution.

  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 implies the usage pattern: call this tool to get a quote, then pass the quoteToken to ravn_execute. It also notes that no API key is required, which is a practical prerequisite. However, it does not explicitly mention alternative tools like ravn_health or when not to use this tool, but the main flow is clear enough for an agent to know when to invoke it.

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

• ravn_healthA
  4.3/5.0
  Behavior3/5

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

  The readOnlyHint and openWorldHint annotations already indicate this is a safe, non-mutating read. The description adds purpose but does not disclose any additional behavioral traits beyond the annotations (e.g., no mention of caching, latency, or failure semantics). It does not contradict the annotations, so a baseline score is appropriate.

  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, compact sentence with a clear benefit clause. It wastes no words and immediately conveys the tool's purpose and usage context. The structure is perfectly scannable for an agent.

  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?

  The description fully covers the tool's role in the overall RAVN workflow (pre-swap health check), enough for an agent to decide when to invoke it. Given the tool's simplicity (no params, no output schema), nothing essential is omitted.

  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?

  The input schema has no properties, and the description adds no parameter details (correctly, since there are none). With no parameters, the schema coverage is effectively complete, and the description does not need to elaborate. No information is missing, so a neutral baseline is suitable.

  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 tool performs a liveness check across all venues RAVN routes through, using a specific verb ('check') and a specific resource ('venue health'). It distinguishes itself from the sibling swap/quote/execute/status tools by focusing on proactive route degradation detection.

  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 to call before a swap to know whether a route is degraded ahead of time, giving both a clear trigger (before swap) and a concrete benefit. This implicitly tells the agent when not to use it (e.g., during execution) and separates it from the execution-oriented siblings.

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

• ravn_btc_prepare_sendA
  4.5/5.0
  Behavior5/5

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

  The description explicitly discloses that it fetches UTXOs and fee rates from mempool.space, that no private key is seen or touched, and that no RAVN server is involved. This is consistent with the readOnlyHint annotation and gives an agent a clear model of the external dependency.

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

  Conciseness3/5

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

  The core purpose is front-loaded, but the description becomes repetitive: mempool.space is mentioned twice and the 'no RAVN server involved' sentence largely duplicates the earlier privacy statement. The signer-count digression adds little operational value for a single-recipient payment.

  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?

  It supplies the necessary workflow context: deposit result to PSBT, then sign and broadcast yourself, with an optional fee-rate override. Since no output schema is present, a little more detail about the exact PSBT output format could improve completeness, but 'ready-to-sign PSBT' is likely sufficient for an agent.

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

  Parameters5/5

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

  Every parameter is already covered in the JSON Schema, and the free-text description reinforces the most important mappings: toAddress is depositAddress and amountSats is depositAmount. It also adds useful constraints such as fromAddress accepting native SegWit or Taproot and feeRateSatsPerVb defaulting to mempool.space's halfHourFee.

  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 action: turning a DEPOSIT-type ravn_execute result into a ready-to-sign PSBT. It gives the exact input mapping (depositAddress + depositAmount) and clearly distinguishes this preparation step from the broader quote/execute/status/health workflow.

  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 clearly positions the tool as the step after ravn_execute for DEPOSIT flows and says it eliminates the need for custom UTXO selection and fee estimation. It does not explicitly enumerate cases where this tool should not be used, though none of the sibling tools appear to provide PSBT preparation.

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

• ravn_statusA
  4.5/5.0
  Behavior5/5

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

  The readOnlyHint annotation already indicates safety, and the description adds useful behavioral nuance by noting that status may be 'unknown' for some venues and that the tool reports honestly rather than guessing. 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 concise, uses two tight sentences, and contains no redundant or unnecessary wording.

  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 parameter set and lack of output schema, the description fully covers the tool's purpose, input sources, and important venue-specific edge cases.

  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?

  The schema already covers all parameters and their meanings; the description mostly restates the same information about quoteToken and ref. It adds little beyond the schema, so it stays at the baseline for high schema coverage.

  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 it polls swap status using a quoteToken and a ref from ravn_execute, and distinguishes this from the related quote, execute, health, and BTC prepare tools.

  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 provides clear context for when to call the tool, namely after ravn_execute, and explains how to interpret unknown statuses. It does not explicitly state when not to use it, but the usage context is strong enough.

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

• ravn_executeA
  4.6/5.0
  Behavior5/5

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

  The description is highly transparent about side effects: it may require an approval transaction, the approval must be mined before proceeding, failure modes are described for both TRANSACTION and SIGNATURE types, and it explicitly states RAVN never takes custody. This matches the annotations and gives the agent important behavioral expectations.

  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 fairly long but each sentence carries important operational detail, such as approval mining, failure modes, and non-custodial behavior. It is somewhat repetitive with the approval explanation, but the structure remains clear and purposeful.

  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 that there is no output schema, the description does a strong job of explaining the possible return shapes, the meaning of executionType, the approval requirement, and failure behavior. It provides enough context for an agent to understand what will happen and what actions may be required.

  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 covers all parameters, and the description adds useful semantics for refundAddress and destinationAddress by labeling them as late-bound. It also explains the apiKey's purpose and links to documentation. This goes beyond the schema without being redundant.

  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 tool's purpose: turning a quoteToken from ravn_quote into an execution payload. It explicitly identifies the source of the input and distinguishes the execution action from quote creation, making its role obvious.

  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 implies the usage context by referencing ravn_quote and explaining the three execution types. It does not explicitly contrast with sibling tools like ravn_status or ravn_btc_prepare_send, but the intended flow is clear and adequately guided.

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