SwapWizard

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

With no annotations, the description fully discloses caching behavior (10-minute TTL, on-demand refresh) and output fields, giving agents full behavioral understanding.

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 concise sentences with no filler. First sentence maps endpoint and purpose, second adds caching and input source. Highly efficient.

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 single-parameter tool with no output schema or annotations, the description covers endpoint, input source, output data, and caching behavior, making it fully self-contained.

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

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

Schema coverage is 100% and the schema description already specifies the id's origin. The tool description adds only minor redundancy, so it meets baseline but does not significantly enhance parameter understanding.

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 maps to a specific endpoint and returns real-time momentum data with enumerated fields. It distinguishes from sibling tool search_liquidity_pools by specifying that the id comes from that tool's response.

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 directs agents to use the numeric id from search_liquidity_pools, providing clear context on when to invoke this tool. Lacks explicit exclusions but sufficient for typical use.

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?

Despite no annotations, the description discloses the tool returns service availability and is a read-only health check. It could be slightly more specific about what 'available' entails, but overall sufficient.

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, no wasted words. Efficiently conveys purpose and usage.

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 parameterless health check with a simple boolean-like return, the description fully covers what is needed. No output schema is necessary.

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?

No parameters exist; schema coverage is 100%. The description adds nothing beyond schema, meeting the baseline of 3.

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

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

The description clearly states the tool checks API health and maps to GET /health, which distinguishes it from sibling tools focused on liquidity pools, quotes, and user positions.

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

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

Explicitly advises using this tool to confirm API responsiveness before operations, providing clear context and when-to-use guidance.

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

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

No annotations provided, so description carries full burden. It describes execution flow (approve, fresh quote, send tx), warns about price impact (must present and confirm), and explains zero output HTTP 400 error. Could be clearer about whether it executes or only quotes, but consistent with get_swap_quote.

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?

Description is detailed but each sentence adds value. Front-loaded with mapping and purpose, then usage, execution flow, warnings. Could be slightly more concise but 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?

Given 9 parameters, 6 required, no output schema, the description provides sufficient context: purpose, usage, execution flow, error conditions, and warnings. No missing critical information.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add semantics beyond the schema, but the schema already documents all parameters adequately.

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 maps to POST /quote with excludePositions=true, is a shortcut to get_swap_quote, and explicitly defines when to use it (agent holds significant position). It distinguishes from sibling get_swap_quote.

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

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

Explicitly describes when to use (agent holds significant position in pool to trade against). While no explicit 'when not to use' is given, the context is clear and contrasts with get_swap_quote.

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 provided, so description carries full burden. It discloses the tool returns a guide and covers specific topics. However, it does not explicitly state that the operation is read-only or idempotent, which would be helpful but not critical for a zero-parameter retrieval 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?

Three front-loaded sentences: first states purpose, second gives usage instruction, third enumerates contents. Every sentence adds value; no wasted words.

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 zero parameters, no output schema, and a simple read-only guide retrieval, the description sufficiently explains what the tool does, when to use it, and what it covers. No additional context is necessary.

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 schema coverage is 100%, so no additional parameter documentation is needed. The baseline for 0 params is 4, and the description adds no param info, which is appropriate.

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

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

The description clearly states the tool returns the complete setup and usage guide for SwapWizard, with a specific verb ('Returns') and resource ('setup and usage guide'). It distinguishes from sibling tools by explicitly instructing to call this FIRST before any other tool, making its unique role clear.

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

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

Explicitly provides when to use: 'Call this FIRST before using any other tool.' This is a clear prerequisite instruction. It also lists covered topics, further guiding usage. No ambiguity about when to invoke.

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 carry the burden. It notes the HTTP mapping and lists chains, but does not explicitly state that it is read-only or idempotent. However, the operation is inherently safe, and the description is accurate. Minimal behavioral context added.

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 very concise: two sentences with no wasted words. It front-loads the HTTP mapping and provides specific examples. Every sentence serves a purpose.

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 simplicity of the tool (no parameters, no output schema, no annotations), the description is mostly complete. It tells the agent what it does and gives examples of return content. Could be slightly more explicit about the output format but sufficient.

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?

There are zero parameters, so the description cannot add meaning beyond the schema. Baseline for 0 parameters is 4. Description does not need to explain parameters.

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 maps to a specific endpoint and lists supported EVM chains with chain IDs and native gas tokens, naming specific examples. This distinguishes it from sibling tools like get_supported_dexes or get_swap_quote.

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 for retrieving supported chains. It does not explicitly state when to use or when not to, but the simplicity of the tool (no parameters) makes the use case self-evident. Lacks explicit alternatives or exclusions.

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 it returns read-only data with no side effects. It clearly describes output and behavior per chain.

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?

Single sentence with no wasted words, front-loaded with purpose and efficient additional details.

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 no output schema, the description adequately explains return structure (name and slug) and usage, sufficient for a simple tool.

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 covers chainId with full description; the description adds minimal extra meaning beyond 'per chain'. Baseline 3 due to 100% schema coverage.

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

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

The description clearly states the tool returns AMMs/DEX sources per chain with display name and slug, distinguishing it from sibling tools like get_supported_chains and search_liquidity_pools.

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?

Provides explicit guidance on using the slug in search_liquidity_pools, but does not explicitly state when to use this tool vs alternatives. 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.

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

With no annotations, the description fully discloses behavioral traits: it never signs or broadcasts, returns signable data only, includes price impact warnings requiring user confirmation, and explains the zero output error. It also mentions surplus and positive slippage handling. This comprehensive disclosure exceeds expectations.

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 well-structured with clear sections (execution flow, warnings) and uses emojis for emphasis. It is informative but somewhat lengthy; however, each part adds necessary context. It is front-loaded with the main purpose, making it efficient for quick reading. A slight reduction for minor redundancy (e.g., repeating 'signable data only' twice).

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?

Despite no output schema, the description details return fields (router, callData, value, price impact, etc.) and error handling. It covers prerequisites, execution steps, and important safety notes. For a complex tool with 8 parameters, this level of completeness ensures the agent can use it 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the 'excludePositions' parameter's purpose and how to obtain the data from 'list_user_lp_positions', and clarifies the 'amount' parameter as uint256 in token decimals. This extra context justifies a score above baseline, though not all parameters are further elaborated.

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 purpose: it maps to POST /quote and returns the best swap quote across DEX protocols with detailed data. It specifies it only returns signable data and does not sign or broadcast. However, it does not explicitly differentiate itself from the sibling tool 'get_clean_quote', which might serve a similar function, thus missing a direct distinction.

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 a detailed execution flow (approve, get fresh quote, send transaction) and prerequisites (private key/wallet signer). It includes warnings about price impact and zero output scenarios. However, it does not explicitly state when to use this tool versus alternatives like 'get_clean_quote' or when not to use it, slightly limiting guidance on tool selection.

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

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

With no annotations, the description fully discloses behavior: it uses Alchemy's NFT APIs for fast discovery, falls back to on-chain scanning (potentially slower and with delayed new positions), and returns a comprehensive set of position details.

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 concise and well-structured, starting with the endpoint mapping, then detailing the API behavior, returned data, and usage guidance. Every sentence adds meaningful information 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?

For a read-only list tool with 3 parameters and no output schema, the description is remarkably complete. It explains the data returned, optimization hints, and how the tool fits into a workflow with 'zap_out_of_lp_position'.

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 covers all parameters with descriptions, but the description adds value by explaining the significance of the 'rpcUrl' parameter (Alchemy key extraction, speed implications) and the 'owner' parameter (wallet address for query).

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 reads all LP positions for a wallet on a given chain, specifies the supported protocols, and distinguishes itself from sibling tools like 'zap_out_of_lp_position' by noting the data flow between them.

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

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

The description provides explicit guidance to call this tool before 'zap_out_of_lp_position' and to pass the returned parameters. It also recommends using an Alchemy RPC URL for faster results, though it does not explicitly list when not to use the tool.

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

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

No annotations are provided, so the description carries full burden. It describes the GET mapping and return fields, implying read-only behavior, but does not explicitly state it does not modify data. However, the parameter descriptions and output field list give reasonable 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.

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

The description is well-structured with an introductory sentence, a key parameters section, and a critical note about ID fields. It is front-loaded with purpose and actionable usage. Slightly verbose due to parameter enumeration, but each 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?

Given 14 parameters, no output schema, and multiple sibling tools, the description covers essential usage context: pagination, sorting, filtering, and the distinction between poolId and id for downstream tools. It could mention pagination metadata, but it is adequate for correct invocation.

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

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

Schema description coverage is 100%, baseline 3. The description adds value beyond schema by explaining the interplay of trending, sortBy, sortOrder, and topPerVenue parameters, and clarifies the meaning of poolId vs id. This compensates for the lack of detail on response structure.

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 'Discovers liquidity pools across supported AMMs and chains' and lists specific output fields. It distinguishes from sibling tools by mentioning it is a required upstream step for zap_into_lp_position and that poolId is distinct from id for use with different 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?

Explicitly states 'Required upstream step before zap_into_lp_position', explains key parameters for trending, sorting, and venue limiting, and provides clear instructions on which ID to use for downstream tools. This gives agents concrete when-to-use and how-to-use guidance.

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

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

No annotations were provided, so the description carries full burden. It discloses mutation (sends tx), requires private key/wallet signer, handles intermediate swaps, returns surplus, includes priceImpact field, and potential 400 error. It also explains execution flow with approve and fresh quote steps.

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 relatively long but every sentence serves a purpose. It is front-loaded with the endpoint and core purpose, followed by important warnings and step-by-step flow. Could be slightly more concise, but structure is logical.

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 no output schema, the description does not fully explain return values but mentions priceImpact field and potential error. It covers usage, constraints, execution flow, and error handling comprehensively. Sibling tools provide context.

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

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

Schema coverage is 100% with all 7 parameters described. The description adds value beyond schema: poolId must be verbatim from search_liquidity_pools, deposits structure explanation, and clarification that tickLower/tickUpper are for concentrated liquidity. Baseline 3 is elevated due to added context.

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 maps to POST /addliquidity/quote and builds a single-transaction zap to enter an LP position from any input token. It distinguishes from siblings like 'zap_out_of_lp_position' and other query tools by specifying the verb 'zap into LP position' and resource 'LP position'.

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

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

The description provides explicit when-to-use guidance: entering an LP position from any token. It gives important notes about poolId origin, execution flow steps, price impact warning, and error handling. It implicitly contrasts with siblings like 'zap_out_of_lp_position' and 'get_swap_quote'.

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 behavioral traits: approval methods for different position types (NFT vs classic), the need to wait for approval confirmation, quotes expiring, and the requirement to present price impact to the user. It also mentions that using 100% for classic pools may revert.

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 well-structured with sections and bullet points, and key information is front-loaded. However, it is fairly long; some details could be slightly condensed without losing clarity. Overall, 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?

Given the tool's complexity (10 parameters, no output schema), the description covers the complete workflow, parameter sources, execution steps, and critical warnings. It references the required sibling tool (list_user_lp_positions) and explains the integration. No output schema is present, so return values are not required.

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

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

Schema coverage is 100%, but the description adds meaning beyond field names and types. It explains how to obtain positionId, nftManager, dexName, liquidityKind from list_user_lp_positions. It provides usage guidance for percent (use 99 for classic pools) and clarifies that withdrawals can be any token.

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 builds a single-transaction zap to exit an LP position into any output token. It specifies the action 'zap out', the resource 'LP position', and a key differentiator (any token, not just underlying). This distinguishes it from sibling tools like zap_into_lp_position.

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 a detailed REQUIRED WORKFLOW: first call list_user_lp_positions, then pass specific fields. It gives an explicit EXECUTION FLOW with steps for approval, waiting, quoting, and sending. It also warns against using 100% for classic pools, recommending 99% to avoid reverts.

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