land_liquidity_quote

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 it does so extensively. It discloses the arithmetic relationship verified at tested values, the clamping behavior for zero/negative amounts, HTTP 400 for non-numeric amounts, 0/0 for unknown pools, and the silent precedence of resource_amount when both are supplied. It also explicitly states that the relationship is observed, not verified across the whole input range, and that the tool reports the upstream quote unchanged.

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 not bloated; every sentence adds meaningful information. It front-loads the core purpose and endpoint, then layers behavioral details. It could arguably be trimmed slightly, but the length is justified by the amount of critical behavioral nuance it conveys. The structure is logical: purpose, relationship, edge cases, trap, and final clarification.

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

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

For a tool with no annotations and no output schema, the description is remarkably complete. It covers the endpoint, the optional parameters, the response contents, the arithmetic relationship, edge cases (zero/negative, non-numeric, unknown pool), the precedence trap, and the upstream passthrough behavior. An agent has everything needed to call this tool correctly and interpret results.

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%, so the description must compensate for the schema's lack of parameter documentation. It does: it explains that resource_amount and dec_amount are optional inputs, that the response carries both quoted amounts, and how the two amounts relate arithmetically. It also explains the precedence behavior when both are supplied. This is far beyond what the bare schema provides.

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

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

The description states a specific verb ('Get'), a specific resource ('the best route in this liquidity family'), and the exact endpoint (GET /land/liquidity/quote/{poolId}). It clearly distinguishes this from sibling tools like land_liquidity_pools and land_liquidity_pool_by_id by focusing on the quote/route behavior rather than pool metadata.

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

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

The description gives clear context for when to use this tool: when you need a pool-specific quote in this liquidity family. It doesn't explicitly name sibling alternatives or state when NOT to use it, but the endpoint reference and the emphasis on 'pool-specific quote' imply the usage context. It also warns about the trap of supplying both amounts, which is a form of usage guidance.

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