hogswap-mcp

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

With no annotations provided, the description fully discloses critical behaviors: the transactions are unsigned, signing occurs only in the user's wallet, and the tool never handles mnemonics or private keys. It also implies that the tool does not submit transactions, leaving that to the user. This is exemplary transparency for a transaction-building tool.

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, front-loaded with the core purpose, and each sentence earns its place. The security warning is essential and adds real value without 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?

Given the tool's complexity, the description covers the essential workflow (build unsigned group, sign, submit) and security requirements. It leverages the existence of an output schema, so details about return values are not needed. It could be more thorough about the exact role of user_address or prerequisites, but it remains sufficiently complete for an agent to use 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 0% description coverage, so the description must compensate for parameter meaning. It only explains quote_id ('for a get_quote quote_id') and indirectly hints at user_address through 'your wallet,' but api_key is completely unexplained. This leaves two of three parameters semantically underexplained.

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 that the tool produces an unsigned transaction group for a get_quote quote_id, which distinguishes it from siblings like get_quote or pay_x402_invoice. However, it lacks an explicit active verb (e.g., 'Builds...') and does not name the resource as 'swap' directly, relying on the tool name for that association.

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

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

The description provides clear usage context by requiring a quote_id from get_quote and instructing the user to sign every transaction with their own wallet and submit as one group. It does not explicitly mention alternatives or when-not-to-use, but the context is sufficient given the tool's unique role among siblings.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only implies a read-only operation but does not mention authentication, rate limits, response format, or side effects. The optional api_key parameter's behavior is not explained.

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, front-loaded sentence that efficiently states the tool's purpose. It is not verbose, though it could add more value with additional context.

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, but with no annotations and no explanation of the api_key parameter or usage context, the description is not fully complete. It would benefit from a note on how the API key is sourced and when to use this instead of get_credit_offer.

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 description does not mention the api_key parameter at all, and schema description coverage is 0%. The schema shows an optional string/null parameter with a default of null, but the description does not clarify whether it overrides authentication or is required.

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 returns the current HOGSWAP credit balance for the API key, which distinguishes it from siblings like get_credit_offer or get_quote. However, it lacks an explicit verb (e.g., 'Gets'), making it slightly less direct.

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 no guidance on when to use this tool versus alternatives, such as get_credit_offer, nor any exclusions or prerequisites. It solely states what it returns.

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 the burden. It adds valuable behavioral context: 402 is a payment instruction, credits land ~1 block after payment, and the nonce must be preserved. It does not mention auth or rate limits, but the protocol-specific nuance 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?

Three sentences, each earning its place. The description is front-loaded with the purpose and immediately gives actionable next steps and timing. 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?

The description covers the essential protocol flow and timing, and an output schema exists so return values need not be described. However, the lack of parameter info leaves a gap, and without that, the overall completeness is slightly reduced.

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 0% and the description never explains the parameters (usdc_micro, api_key). The name 'usdc_micro' hints at amount, but the description provides no meaning or relationship to the offer.

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: creating a credit top-up and obtaining an x402 offer. It explains that HTTP 402 is the payment instruction, not an error, and explicitly references the sibling tool pay_x402_invoice, distinguishing this from other tools.

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

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

The description gives explicit guidance on how to use the result: feed accepts[0] into pay_x402_invoice and keep the note nonce. It implies the proper workflow, though it lacks explicit when-not-to-use or alternative 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?

With no annotations, the description carries the full burden. It discloses key behaviors: exact input vs exact output modes, base units (µ), asset 0 = ALGO convention, output fields (expected_out, route legs, quote_id), and the optional sender for fee discounts. This far exceeds what the schema alone provides.

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 three concise sentences that front-load the purpose, then detail input/output conventions and the fee discount feature. Every sentence adds value with no repetition or filler.

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 6 parameters, exact input/output modes, and multiple return fields, the description provides a strong overview including return values and unit conventions. The primary gap is the unexplained api_key parameter, and it doesn't explicitly address rate limits or permissions (though not critical for a quote tool). Overall, it is quite complete.

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?

Given 0% schema description coverage, the description compensates by explaining the roles of amount, amount_out, sender, and the asset ID convention. It does not mention api_key at all, leaving that parameter semantically unexplained, so it's not a perfect 5.

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 it provides a 'HOGSWAP swap quote across every Algorand DEX', with a specific verb (quote), resource (swap), and scope (every DEX). It also distinguishes itself from the sibling build_swap by noting the returned quote_id is intended for that tool.

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 implies use before build_swap by stating it 'Returns... a quote_id for build_swap'. It also explains the two input modes (amount vs amount_out) which helps the agent choose the correct parameter. However, it doesn't explicitly state when not to use this tool or mention alternatives, so it earns a 4 rather than 5.

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

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

With no annotations, the description carries the burden of disclosing behavior. It adds valuable context by noting the price-confidence gating and the always-included ALGO/USDC, which are non-obvious. However, it does not mention output format or further behavioral details, so it is adequate but not exhaustive.

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, dense sentence that communicates the tool's purpose and key constraints without any fluff. Every phrase adds information, making it highly concise and well-structured.

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 zero-parameter list tool with an output schema, the description adequately covers what the tool lists and the gating behavior. It does not explain return values, but the output schema handles that, and the complexity is low, so it is reasonably complete.

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 tool has zero parameters, and the schema reflects this with 100% coverage. The description correctly does not need to explain parameters, and the baseline for zero-parameter tools is 4.

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 identifies the tool's purpose as listing assets accepted for pay_x402_invoice and credit top-ups. It uses a specific verb ('list') and resource ('payable assets'), and the detail about price-confidence gating and guaranteed inclusion of ALGO/USDC distinguishes it from sibling tools.

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

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

The description implies usage context by mentioning pay_x402_invoice and credit top-ups, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or conditions. It gives clear context but lacks explicit 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?

With no annotations provided, the description fully carries the burden. It discloses key behavioral traits: returns UNSIGNED groups, sign all in one pass, submit IN ORDER, swap-first floor guarantee, and that signing happens in the user's wallet. It also warns against passing mnemonics/private keys, addressing security behavior not captured elsewhere.

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 dense but every sentence carries necessary information. It front-loads the core purpose, then provides operational details, unsupported cases, and security warnings. Slightly long, but the complexity of the tool justifies the length.

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 (nested objects, no property schemas, 0% schema coverage), the description is remarkably complete. It covers what settles on Algorand, asset flexibility, return format, signing flow, ordering constraints, swap flooring, unsupported EVM, and security. An output schema exists, so not explaining return values is acceptable.

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 0%, so the description must compensate. It adds significant meaning to the two core parameters: 'Pass the `accepts` entry you picked as `invoice` (keep its note!)' and 'single input with no amount = minimum solved'. It does not clarify user_address or api_key, but the most complex parameters get meaningful guidance.

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+scope: 'Pay ANY Algorand-settled x402 invoice'. It also adds flexibility details (1-4 routable assets, holding none of the demanded asset) that clearly distinguish it from sibling tools like build_swap or get_quote, which serve different purposes.

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 explicit when/when-not context ('EVM invoices unsupported'), operational instructions (pass the accepts entry as invoice, keep its note, single input with no amount = minimum solved), and submission order requirements. It does not explicitly name alternative tools, but the scope is well-defined.

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 fully discloses the challenge-response behavior, including that signing happens in the user's wallet and not in the tool, and that secrets must never be shared. It also clarifies that the tool returns a challenge rather than completing registration.

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 with clear front-loading of purpose and step, plus a critical security warning. Every sentence adds value.

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 one-parameter step in a two-step flow, the description covers purpose, expected output, next step, and security context. The presence of an output schema means return format specifics are not required in the description.

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 schema provides only an 'address' parameter with no description (0% coverage). The description contextualizes it as the address whose key is used for signing, but doesn't explicitly define the parameter's format or details, leaving some interpretation.

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 this is step 1 of a self-service HOGSWAP API key registration, and explicitly distinguishes it from verify_registration (the next step). It identifies the action (registering an agent) and the output (a challenge).

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 explicitly instructs to sign the challenge and then call verify_registration, providing a clear workflow. It also warns to never pass mnemonics/private keys, establishing security-related usage boundaries.

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 provided, the description carries the full burden of behavioral disclosure and succeeds in highlighting the most critical trait: the key is returned only once, is not recoverable, and is not stored on the server. This is essential for preventing data loss. It could add more detail on failure modes or what happens to the registration state, but the core behavior is well covered.

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 just two sentences, with every word earning its place. The critical warning about one-time key retrieval is front-loaded, and the usage instruction for later calls is concise. There is zero redundancy or filler.

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 excels in conveying the tool's purpose and the one-time key behavior, which is contextually important for a key-issuance flow. However, it is incomplete for a tool with three undocumented parameters and no annotations, and it does not explicitly connect to the sibling register_agent step. The presence of an output schema reduces the need to describe return values, but parameter semantics remain a significant gap.

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 provides zero description coverage for the three required parameters (address, challenge, signature_b64), and the description does not compensate. It gives no hints about what these fields represent or how they should be populated, leaving the agent with insufficient guidance for correct invocation.

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: 'Self-service key issuance, step 2 of 2' and 'Returns your hsk_ key ONCE', distinguishing it from sibling tools as the final step that returns the API key. The verb and resource are specific and unambiguous.

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 establishes clear sequential context as 'step 2 of 2', implying it follows register_agent. It also provides explicit guidance on how to use the key in subsequent calls ('Send it on later calls as Authorization: Bearer, X-API-Key, or the api_key argument'). However, it does not explicitly name alternatives or state exclusions.

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