getTokenPools

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds key behavioral traits: it is 'Read-only and keyless', outlines the pagination structure (results, has_next_page, next_cursor), and explicitly states that unknown addresses return empty results (not errors) and unsupported parameters cause errors. This fully informs the agent about the tool's behavior.

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 (around 150 words) and well-structured: first sentence states purpose, followed by usage examples, behavioral notes, and a succinct parameter summary. Every sentence serves a clear purpose with no redundancy or fluff.

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 the good coverage, the description omits mention of the required 'rationale' parameter, which has constraints (20-500 chars) and is critical for the tool to function. It also fails to list deprecated/unsupported parameters like 'address' and 'reorder'. These gaps reduce completeness, as the agent needs to know all required inputs and potential error sources. An output schema exists, compensating for return values, but the required param omission is significant.

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 has 100% description coverage, so the baseline is 3. The description adds value by summarizing the essential parameters (network, token_address, limit, cursor, sort_by, sort_dir) with their defaults and aliases (e.g., 'sort_dir asc/desc (default 'desc', alias sort)'). This concise overview helps the agent quickly understand the key params, going slightly beyond the schema alone.

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 retrieves liquidity pools containing a specific token on a given network, with pagination details. It distinguishes from sibling tools like getTokenDetails by explicitly directing price queries elsewhere, and the use-case examples ('which pools hold WETH on ethereum?') 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 provides explicit usage scenarios ('Use for ...'), tells when not to use it ('For the token's own price use getTokenDetails'), and advises to run search first if the network is unknown. It also explains error behavior for unknown addresses, giving clear guidance on when to expect empty results.

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